Supplier orders

Use supplier order operations when a merchant integration needs to create purchasing workflows, update line items, or mirror supplier order states.

Available operations

• List and filter supplier orders with supplierOrders, or load one by global ID with supplierOrder.
• List supplier order line items with supplierOrderLineItems, or load one by global ID with supplierOrderLineItem.
• Create a supplier order with createSupplierOrder.
• Add, update, and remove line items with addSupplierOrderLineItem, updateSupplierOrderLineItem, and removeSupplierOrderLineItem.
• Update the expected delivery date with updateSupplierOrderExpectedDeliveryDate.
• Write the merchant's custom fields with setSupplierOrderCustomFields. It merges the given keys into the existing ones and accepts only custom fields defined for supplier orders.
• Move the order through purchasing states with markSupplierOrderAsConfirmed, markSupplierOrderAsOrdered, or cancelSupplierOrder.
• Cancel what the supplier will not deliver any more with cancelOpenSupplierOrderQuantities.
• Update the payment state with markSupplierOrderAsPaid, markSupplierOrderAsPartiallyPaid, or markSupplierOrderAsUnpaid.
• Delete a supplier order with deleteSupplierOrder.

States

A new supplier order starts in state open and with the payment state open. The state field carries the technical name of the order state:

• confirmed is set by markSupplierOrderAsConfirmed, sent (sent to the supplier) by markSupplierOrderAsOrdered, and cancelled by cancelSupplierOrder.
• partially_delivered and delivered have no mutation. They change automatically once a goods receipt of type Supplier that receives against the order is approved, see Goods receipts.
• completed is set in Pickware, not through the API.

The paymentState field moves between open, partially_paid and paid through the three payment mutations.

When the supplier will not deliver the rest of a partially delivered order, cancelOpenSupplierOrderQuantities cancels the outstanding quantity of every open line. The ordered quantities, prices and totals stay as they are, the cancelled quantity leaves the incoming stock, and the order settles to delivered on its own. It fails with CONFLICT on an order without an approved goods receipt; cancel such an order with cancelSupplierOrder instead.

Example: create a supplier order

mutation CreateSupplierOrder($input: CreateSupplierOrderInput!) {
  createSupplierOrder(input: $input) {
    id
    number
    state
    paymentState
  }
}

{
  "input": {
    "supplierId": "U3VwcGxpZXI6MDE4...",
    "lineItems": [
      {
        "productSupplierConfigurationId": "UHJvZHVjdFN1cHBsaWVyQ29uZmlndXJhdGlvbjow...",
        "quantity": 24
      }
    ]
  }
}

The input references product-supplier configurations, not raw products. A line without a unitPrice takes the net purchase price its configuration holds in the order's currency, or 0 when there is none. Use Product-supplier configurations to find or create those assignments first.

In createSupplierOrder and addSupplierOrderLineItem, every configuration must belong to the supplier of the order. If a configuration belongs to another supplier, the mutation fails with BAD_REQUEST. If a configuration does not exist, it fails with NOT_FOUND. In both cases, the mutation writes no supplier order and no line item.