Introduction
In Odoo, models define how data is structured and stored in the database. Every piece of business data you work with, from sales orders to inventory transfers to warehouse operations, lives in a model.
Understanding Odoo models is essential for both developers and functional consultants. Models are the foundation of the Odoo data architecture. They define fields, relationships, and business logic.
This article focuses on one of the most important models in the Inventory app: stock.picking. Whether you are building custom warehouse modules, integrating external systems, or configuring workflows, you will work with this model.
What is the stock.picking Model
The stock.picking model represents transfers in Odoo. It is the central place where warehouse operations are tracked. Each picking record represents a single transfer of goods from one location to another.
This model in Odoo is used across the Inventory module. Receipts, deliveries, and internal transfers all create stock.picking records. When you confirm a delivery order from a sale, receive goods from a purchase, or move stock between warehouses, you are creating or updating a stock.picking record.
The model is defined in the stock module. Other modules extend it through Odoo model inheritance. Sale adds delivery-related fields. Purchase adds receipt workflows. Manufacturing adds production moves. Each module adds what it needs without duplicating the core structure.
The stock.picking model inherits from mail.thread and mail.activity.mixin. This means you can track changes, add chatter messages, and schedule activities on transfers directly.
Key Fields in the Model
Here are the most important Odoo fields in the stock.picking model. Understanding these will help you work effectively with transfers and warehouse operations.
1. name
Type: Char. This field stores the reference of the transfer. It is typically auto-generated from a sequence (e.g. WH/OUT/00001). It is displayed in the header of transfer forms and is the primary identifier for the picking.
2. origin
Type: Char. The source document reference. For a delivery, this might be the sale order name. For a receipt, the purchase order. It helps trace where the transfer originated.
3. state
Type: Selection. The status of the transfer. Values: Draft, Waiting Another Operation, Waiting, Ready, Done, Cancelled. Each state drives what actions are available. Odoo computes this from the related stock moves.
4. picking_type_id
Type: Many2one (stock.picking.type). The operation type. Defines whether this is a receipt, delivery, or internal transfer. Required. Each picking type has default source and destination locations.
5. move_ids
Type: One2many (stock.move). The stock moves. Each line represents a product and quantity to move. This is the core of the transfer. All reservation and availability logic works on these moves.
6. move_line_ids
Type: One2many (stock.move.line). The detailed operations. When you have lot or serial tracking, these lines store the specific lots and locations. Used for picking, packing, and validation.
7. location_id
Type: Many2one (stock.location). The source location. Where products are taken from. Required. For deliveries, this is usually the stock location. For receipts, the supplier location.
8. location_dest_id
Type: Many2one (stock.location). The destination location. Where products are moved to. Required. For deliveries, this is usually the customer location. For receipts, the stock location.
9. partner_id
Type: Many2one (res.partner). The contact. For deliveries, the customer. For receipts, the supplier. Used for address on documents and for carrier integration.
10. scheduled_date
Type: Datetime. When the transfer is scheduled to be processed. Used for planning and prioritization. Setting it manually sets the expected date for all stock moves.
11. date_deadline
Type: Datetime. The deadline. Often comes from the sale order or purchase order. Used to flag late transfers and for customer promise dates.
12. date_done
Type: Datetime. When the transfer was validated or cancelled. Read-only. Set automatically when the picking is done.
13. priority
Type: Selection. The priority level. Products are reserved first for transfers with higher priority. Used for urgent orders.
14. move_type
Type: Selection. The shipping policy. Values: As soon as possible (partial delivery allowed) or When all products are ready (all or nothing). Affects when the picking can be processed.
15. user_id
Type: Many2one (res.users). The responsible user. Used for assignment and workload tracking. Defaults to the current user when creating.
16. company_id
Type: Many2one (res.company). The company. Related from the picking type. In multi-company setups, this determines which company owns the transfer.
17. group_id
Type: Many2one (procurement.group). The procurement group. Links related moves together. Used when multiple pickings come from the same order.
18. backorder_id
Type: Many2one (stock.picking). When a transfer is partially validated, a backorder is created for the remaining. This field links to the original picking.
19. backorder_ids
Type: One2many (stock.picking). The back orders created from this picking. Used when you validate partially and need to process the rest later.
20. return_id
Type: Many2one (stock.picking). If this picking was created as a return, this links to the original picking. Used for return workflows.
21. note
Type: Html. Internal notes. Visible to warehouse users. Can include special instructions or handling requirements.
22. signature
Type: Image. The signature captured when the delivery is validated. Used for proof of delivery. Stored as an attachment.
23. is_signed
Type: Boolean. Computed from signature. Indicates whether the delivery has been signed.
24. owner_id
Type: Many2one (res.partner). The owner to assign when validating. Used for consignment or when products belong to a third party.
25. package_level_ids
Type: One2many (stock.package_level). Package levels when using put in pack. Groups move lines into packages for shipping.
26. create_date
Type: Datetime. When the record was created. Automatically managed by Odoo. Inherited from the base model.
27. write_date
Type: Datetime. When the record was last modified. Automatically managed. Inherited from the base model.
28. active
Type: Boolean. Soft delete flag. When False, the record is archived. Inherited from the base model.
How This Model Is Used in Business Workflows
1. Sales and Delivery
When a sale order is confirmed, Odoo creates a delivery order (stock.picking). The picking links to the sale order via origin. Warehouse staff pick and pack, then validate. The state moves from draft to ready to done.
2. Purchase and Receipt
When a purchase order is confirmed, Odoo creates an incoming receipt. The picking receives products from the supplier location to stock. The partner_id is the supplier. Validation updates inventory quantities.
3. Internal Transfers
Moving stock between warehouses or locations creates internal pickings. The picking_type_id has code 'internal'. Location and destination are both internal stock locations.
4. Returns and Backorders
When a sale is returned, a return picking is created. The return_id links to the original delivery. When a delivery is partially validated, backorder_ids holds the remaining work.
5. Manufacturing and Production
Manufacturing orders create pickings for raw materials (consumption) and finished products (production). The stock.picking model is extended by the mrp module for these flows.
How Developers Extend This Model
Developers extend stock.picking using several patterns. Odoo model inheritance is the main mechanism.
Model Inheritance
Use _inherit = 'stock.picking' to extend the model. Add new fields, override methods, or add constraints. The inherit model in Odoo keeps your changes in a separate module for easy upgrades.
Adding Fields
Define new Odoo fields in your inherited model. Use the right field type: Char, Many2one, Boolean, Integer, Text, Selection. Consider company-dependent fields for multi-company.
Python Extensions
Override button_validate, action_assign, or _create_backorder to add logic. Use super() to call the original. Be careful with state transitions and move creation.
Odoo Studio
Odoo Studio lets you add fields without code. Good for quick customizations like custom labels or extra notes. For complex logic or carrier integration, custom modules are more maintainable.
Best Practices
- Always set the picking_type_id when creating pickings manually. It drives default locations and behavior.
- Use the origin field to trace back to the source document. It helps with reporting and debugging.
- When building API integrations, the stock.picking model is fully exposed via the Odoo API. Create moves via the move_ids relation. Do not create pickings without moves.
- Use scheduled_date for planning. It affects reservation and prioritization.
- For custom fields, use the
x_prefix or a module prefix to avoid conflicts with future Odoo versions.
Common Mistakes
- Creating pickings without setting picking_type_id. This can lead to wrong default locations.
- Modifying move_ids after confirmation without understanding the state machine. State transitions can be complex.
- Forgetting to set partner_id for deliveries. Carriers and documents need the contact.
- Overriding button_validate without calling super(). This can break backorder creation and other modules.
- Assuming move_ids and move_line_ids are always in sync. Move lines are created when you reserve or when you use detailed operations.
Conclusion
The stock.picking model is central to Odoo inventory. It stores transfers, deliveries, and receipts. Understanding its fields and how modules extend it will help you configure, customize, and integrate Odoo effectively.
Whether you are a functional consultant mapping warehouse processes or a developer building custom modules, a solid grasp of stock.picking will save time and prevent errors.
Ready to Optimize Your Odoo Warehouse
Dasolo helps companies implement, customize, and optimize Odoo. We specialize in API integrations and Odoo development. Our team has deep experience with the Odoo data architecture and models like stock.picking.
If you need help with your Odoo implementation, custom warehouse modules, or integrations, we are here to help. Book a demo to discuss your project.