# Orders and Deliveries
This section will guide you through the core principles on how Orders and Deliveries are handled within the Procurement application, how they can be created, updated and accessed.
# Object Graph
┌─────────────────────┐ ┌─────────────────────┐
│ Contracts │ │ SKU │
└─────────────────────┘ └─────────────────────┘
▲ ▲
│ │
│ │
│ │
┌ ─ ─ ─ ─ ─ ─ ─ ┼ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┼ ─ ─ ─ ─ ─ ─ ─ ┐
│ │
│ │ │ │
┌─────────────────────┐ ┌─────────────────────┐
│ │ Order │◀────────│ OrderLineItem │ │
└─────────────────────┘ └─────────────────────┘
│ ▲ ▲ │
│ │
│ │ │ │
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ Delivery │◀────────│ DeliveryLineItem │
│ └─────────────────────┘ └─────────────────────┘ │
│ │
─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
# General Concepts - Orders and Deliveries
The concept of an order is structured into different parts. The Order holds that status of the order and connects to the Contract. An order has many OrderItemLines which tell how many pieces (amount) of an specific SKU you want to order. When you add an order line item that Item is updated with a catalog_price which is the best price the Procurement Platform was able to find at the moment.
Next to an order there are one to many Deliveries. The delivery allows to store information when and where to deliver the order goods. This allows you to split one order into multiple delivieries for different locations or to be delivered on different days. It depends on the supplier if the supplier allows multiple deliveries per order (Sappi, for example, doesn't support multiple deliveries).
Note that if you want to order an article for a price only available via an exclusive sales group then you need to set the order's exclusive_sales_group_id to that sales group and you cannot add other article to that order unless these articles have prices in the same sales group.
# Placing an Order
When an order is placed by a customer the procurement platform will inform the supplier and it is up to the supplier to download the order, transfer it into their systems and update the order's status (e.g. to confirmed) when this is done.
When the supplier updates the order the Procurement Platform will fire suitable events: procurement_consumers.order_transferred, procurement_consumers.order_confirmed, procurement_consumers.order_shipped, etc.
# Order Optimization
Depending on the number of SKUs and prices for a variant it might be a bit confusing to understand what is actually the cheapest combination for a required amount of goods. Imagine you need 8000 sheets of paper, and there are the following options
| SKU | amount in base unit | minimum order qty | price |
|---|---|---|---|
| 1 | 1000 sheets | 1 packs | 10.00 |
| 2 | 1000 sheets | 5 packs | 9.00 |
| 3 | 10000 sheets | 1 packs | 80.00 |
then the OrderLineSuggestions (opens new window) API endpoint can tell you that ordering 8 times the SKU 2 would be the cheapest option. But when you need 9000 sheets it would recommend ordering the SKU 3 instead. Note that this API endpoint optimizes only the total price of the order, it does not necessarily find an exact match with the required amount. It might recommend ordering an SKU combination with a higher amount of the goods as required if that leads to a cheaper total price.
# Order Status
The order's status should refect the overall status of the order and its delivery. It is up to the supplier to keep the status of the order up-to-date. Possible states are:
| State | Finite | Description |
|---|---|---|
| draft | ❌ | Initial state of an order, not placed yet |
| placed | ❌ | Order was placed by the consumer, but not yet processed by the supplier |
| transferred | ❌ | Supplier transferred the order into their systems |
| confirmed | ❌ | Supplier confirmed that the order was accepted. At this stage the supplier should confirm the prices and the delivery date too |
| producing | ❌ | Order is produced or packed |
| partially_shipped | ❌ | Order is already partially shipped to the customer |
| shipped | ✅ | Order is fully shipped to the customer |
| cancelation_requested | ❌ | The consumer asked to cancel this order, but the order is in a state in which the supplier must agree |
| canceled_by_consumer | ✅ | Order was canceled by the consumer |
| canceled_by_supplier | ✅ | Order was canceled by the supplier |
| partially_shipped_remainder_canceled | ✅ | Rest of the order was canceled after being partially shipped |
Orders can be change by the consumer in draft and placed state. Suppliers can change orders in all other states until the order reaches a finite state. When you want to cancel an order in a later stage then you want to set the state to cancelation_requested and await confirmation by the supplier.