# 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 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.