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 accessed and how access to them is managed.

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 have been ordered, furthermore an order line item has a catalog_price that is the best price the Procurement Platform was able to find for the specific customer at the moment of placing the order.

Next to an order there are one to many Deliveries. The delivery stores information about when and where to deliver the order goods. The fact that there might be more than one delivery per order allows the customer to split one order into multiple deliveries for different locations or to be delivered on different days. Please note that the amount of delivery line items might be lower than the amount of order line items; this basically means that the customer already ordered an item but did not make a decision in the delivery date or where to deliver.

Receiving an Order

When an order is placed by a customer, the procurement platform will fire a procurement_supplier.order_placed event.

Once you've received an order you should download the order and transfer it immediately into your systems and update the order's status (e.g. to confirmed) when this is done.

Order Status

The order's status should reflect 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 consumers in draft and placed state. Suppliers can change orders in all other states until the order reaches a finite state.

Handling cancellation requests

Customers may sometimes wish to cancel their order after it has been placed. In this case, a procurement_supplier.order_cancelation_requested event is emitted. At this point you must decide whether you wish to cancel the order:

PATCH /suppliers/api/v1/orders/:id
{ "order": { "state_event": "accept_cancelation" } }

Alternatively, you may reject the cancellation and put the order back in the previous state (optionally specifying state_reason to be passed to the customer):

PATCH /suppliers/api/v1/orders/:id
{ "order": { "state_event": "reject_cancelation", "state_reason": "Order has already been shipped" } }