Orders

Orders involve two roles and two messages: as the selling shop the store sends SKUU the seller order, and as the shipping shop it receives a shipping order from SKUU. In between, SKUU decides which shop ships.

1. The online store sends order.created

1. The online store. A customer buys a coat the store does not have but that was available on its SKUU_Network location, and pays.
2. The store's platform. Sends one order.created event with the whole order: the store's order id, the delivery address, every line, and per line the location it is allocated to. The coat is on the store's SKUU_Network id; a pair of socks from the store's own stock is on the store's own location id.
3. SKUU. Checks the signature, that the order is paid and in the store's currency, and stores the seller order. It keeps only the lines allocated to SKUU_Network; the store's own lines are ignored.
4. SKUU. Chooses the shipping shop for each network line: a shop that has the article in stock, ships to the destination country, and is not the selling shop itself. When several qualify, stock and distance decide. SKUU routes only to the destination countries on the environment sheet.
5. SKUU. Creates the shipping order at that shop; that is direction 2 below.
6. SKUU. Answers 200. Invalid payloads, unpaid orders and a mismatched currency receive a permanent 4xx; see Errors and retries. A 200 confirms intake, not physical shipment.

{
  "spec_version": "1",
  "event": "order.created",
  "event_id": "evt_order_01JABC",
  "occurred_at": "2026-09-01T10:15:00Z",
  "data": {
    "order_id": "ORD-10045",
    "order_number": "10045",
    "created_at": "2026-09-01T10:14:55Z",
    "payment_status": "paid",
    "currency": "EUR",
    "tags": ["consumer-order"],
    "shipping_address": {
      "name": "A. Customer",
      "company": null,
      "address_line1": "Example Street 10",
      "address_line2": null,
      "zip": "1000 AA",
      "city": "Amsterdam",
      "province": null,
      "country_code": "NL",
      "phone": "+31000000000",
      "email": "[email protected]"
    },
    "line_items": [
      {
        "line_item_id": "LINE-1",
        "variant_id": "V-123-38-BLK",
        "barcode": "8712345678901",
        "sku": "WC-38-BLK",
        "quantity": 1,
        "unit_price": 249.95,
        "fulfillment_location_id": "900"
      }
    ],
    "subtotal": 249.95,
    "total_discounts": 0,
    "shipping_cost": 0,
    "total_tax": 43.38,
    "total_price": 249.95
  }
}

Prices, discounts and shipping

The same SKUU pricing logic processes Shopify and Connect orders: product gross value minus the product discount, then VAT and the agreed revenue split. Shopify supplies discounts allocated per line; Connect supplies total_discounts, which SKUU allocates in proportion to each line's gross value across the whole order. Shipping is allocated by gross value too.

This is why order.created carries the whole order and not only the network lines. A customer who buys a coat the network ships and a pair of socks the store ships itself has one discount and one shipping charge across both. If only the coat were sent, SKUU would put the entire discount on that one line and pay the shipping shop too little.

For example, a customer buys one item the network ships for €121 and one item the store ships itself for €60.50, before discounts, with a €18.15 product discount and €6.05 shipping. Send unit_price: 121 and unit_price: 60.5, total_discounts: 18.15, shipping_cost: 6.05, and total_price: 169.4. Both lines have quantity 1. All these amounts include VAT.

With 21% consumer VAT, the network product contributes €90 before VAT. If this example's agreed shipping-shop rate is 87%, its product payout is €78.30 before VAT. For a Netherlands shipping shop with 21% injection VAT, SKUU sends POST /orders with unit_price: 94.74. The actual rates come from the participating shops and variants; 87% is an example, not a value to hardcode. SKUU settles allocated shipping separately at its full value before VAT, without a revenue-split deduction. The Connect shipping-order payload contains the product payout lines; it does not carry a separate shipping-charge field.

Do not discount unit_price and then send the same discount again in total_discounts. Optional subtotal, total_tax and total_price are reconciliation values; they do not override the line-price calculation.

2. SKUU calls POST /orders

1. SKUU. Groups the network lines by shipping shop, one order per shop, and calls that shop's POST /orders. The request carries SKUU's reference, the complete delivery address, and the lines with SKUU's line references.
2. The store's platform. Creates the order as paid and tagged skuu_ship, so the store's own logic can tell it apart from the store's own orders. The store collects nothing from the customer: the customer paid the selling shop, and SKUU settles with the shipping shop.
3. The store's platform. Answers 200 with the required receipt fields, including the store's own order_id. Store SKUU's external_ref next to it; both are needed for tracking and returns.
4. The online store. Picks, packs and ships. The package goes to Fulfilment.

{
  "external_ref": "skuu-order-01JABC",
  "tag": "skuu_ship",
  "payment_status": "paid",
  "currency": "EUR",
  "ship_to": {
    "name": "A. Customer",
    "company": null,
    "address_line1": "Example Street 10",
    "address_line2": null,
    "zip": "1000 AA",
    "city": "Amsterdam",
    "province": null,
    "country_code": "NL",
    "phone": "+31000000000",
    "email": "[email protected]"
  },
  "shipping_method": {"code": "standard", "title": "Standard carrier delivery"},
  "line_items": [
    {"external_ref": "skuu-line-01JABC", "variant_id": "V-123-38-BLK", "barcode": "8712345678901", "sku": "WC-38-BLK", "quantity": 1, "unit_price": 249.95}
  ]
}

{
  "success": true,
  "message": "Successfully created order.",
  "external_ref": "skuu-order-01JABC",
  "order_id": "5001",
  "status": "created"
}

Return 200 with success: true, the references and status: "created". The message is optional and extra response fields are ignored. SKUU retries 429, 5xx and timeouts three times; any other 4xx stops the order and alerts SKUU customer service.

Need more on the order?

The request above is the minimum that creates a shippable order. If the store's platform needs more to create an order, for example the item title on each line, the order totals, a customer note for the carrier, or the selling shop's order number for customer service, SKUU adds those fields for the online store on request. Additions are agreed per shop and only ever add optional fields, so an integration never receives a field it did not ask for. Raise it on the onboarding call or with the SKUU contact.

The next page is Fulfilment. The exact contract is on Send an event and Create a shipping order.