Fulfilment

Fulfilment closes the loop on an order: as the shipping shop the store reports every package it ships, and as the selling shop it receives that tracking on the seller order, so the customer gets one shipment notification with a real tracking number.

1. The online store sends fulfillment.shipped

1. The online store. The store packs the shipping order SKUU created and hands the parcel to the carrier.
2. The store's platform. Sends one fulfillment.shipped event per package with the shipping order id, SKUU's order reference, every line in the package, and the tracking number, carrier and tracking URL.
3. SKUU. Checks the signature and matches the package to the shipping order: the store's order_id, SKUU's external_ref, and per line SKUU's line external_ref, the variant and the full quantity of the line. A package that does not match is rejected with 422 invalid_fulfillment and is not recorded.
4. SKUU. Stores the package once, even if the event arrives twice.
5. SKUU. Puts the tracking on the seller order at the selling shop; that is direction 2 below.
6. SKUU. Answers 200. When SKUU cannot finish, for example because the shipping order is not visible yet or the tracking did not reach the selling shop, it answers 503: send the same event again, with the same event_id. A package that was already stored is never stored twice. If the 503 keeps coming back past the retry window, contact SKUU: the package may already be stored and only the last step failed.

{
  "spec_version": "1",
  "event": "fulfillment.shipped",
  "event_id": "evt_ship_01JABC",
  "occurred_at": "2026-09-02T08:30:00Z",
  "data": {
    "fulfillment_id": "FUL-5001",
    "order_id": "5001",
    "external_ref": "skuu-order-01JABC",
    "created_at": "2026-09-02T08:29:50Z",
    "line_items": [
      {
        "line_item_id": "SHIPPING-LINE-1",
        "external_ref": "skuu-line-01JABC",
        "variant_id": "V-123-38-BLK",
        "quantity": 1
      }
    ],
    "tracking_number": "TRACK123",
    "tracking_company": "Carrier",
    "tracking_url": "https://carrier.example.com/track/TRACK123",
    "shipment_status": "in_transit"
  }
}

2. SKUU calls PUT /orders/{order_id}/tracking

1. SKUU. Receives a package from the shipping shop, as in direction 1.
2. SKUU. Calls PUT /orders/{order_id}/tracking on the store's API, once per package. order_id in the path is the seller order id from order.created; the lines are the store's own line_item_id values from that event. An order with lines from several shipping shops gets one request per package, so the same order can receive more than one.
3. The store's platform. Adds the tracking to those lines, marks them shipped, and sends the customer one shipment notification for this package. When the request carries note, keep that text with the order: it tells the customer where to send a return.
4. The store's platform. Answers 200 with the required receipt fields. The same external_ref again must return the same answer without a second notification.

PUT {your_api_root}/orders/ORD-10045/tracking

{
  "external_ref": "skuu-fulfillment-01JABC",
  "created_at": "2026-09-02T08:29:50Z",
  "line_items": [
    {
      "line_item_id": "LINE-1",
      "variant_id": "V-123-38-BLK",
      "quantity": 1
    }
  ],
  "tracking_number": "TRACK123",
  "tracking_company": "Carrier",
  "tracking_url": "https://carrier.example.com/track/TRACK123",
  "note": "Return instructions: send returns for this package to Return 5001, Teststraat 1, 1000 AA Amsterdam, NL. Items: 1x V-123-38-BLK."
}

{
  "success": true,
  "message": "Successfully updated order tracking information.",
  "external_ref": "skuu-fulfillment-01JABC",
  "order_id": "ORD-10045",
  "status": "tracking_updated"
}

Return 200 with success: true, the unchanged references and status: "tracking_updated". The message is optional and extra response fields are ignored. SKUU retries 429, 5xx and timeouts three times. Any other answer stops the update: the package stays stored at SKUU and SKUU customer service retries by hand.

The next page is Cancellation. The exact contract is on Send an event and Add tracking to an order.