Orders and fulfilment (Phase 2)

Phase 2 contract — ready for customer implementation. SKUU's four
integration legs are implemented and locally proven against the deterministic
reference customer. A customer must still implement this contract and pass the
joint conformance session before traffic is enabled. This is not a production
activation notice.

This guide adds order and fulfilment flows to the stable product and inventory
integration. Complete Phase 1 before starting these endpoints.

Overview

Phase 2 reuses the Phase-1 credentials:

• customer-to-SKUU webhooks use the shared HMAC secret;
• SKUU-to-customer requests use the customer-issued bearer token and the same
  shared HMAC secret; and
• testing and production use separate URLs and credentials.

What the customer implements

Before the joint conformance session, the customer prepares exactly four
capabilities:

1. emit signed order.created events from paid consumer orders;
2. accept signed, bearer-authenticated POST /orders requests idempotently;
3. emit signed fulfillment.shipped events for shipped packages; and
4. accept signed, bearer-authenticated
   PUT /orders/{order_id}/tracking requests idempotently.

Keep all recurring sends disabled until SKUU explicitly opens the testing
window. Use synthetic customer data during conformance. No new credentials are
needed when the Phase-1 testing bearer and HMAC secret are still active.

Shared request rules

Body-bearing requests use:

Content-Type: application/json
X-SKUU-Signature: sha256=<lowercase hexadecimal HMAC-SHA256>

Calculate the signature over the exact raw UTF-8 JSON bytes sent on the wire:

HMAC-SHA256(shared_secret, exact_raw_request_body_bytes)

Verify the signature before parsing JSON or performing a side effect. Changing
whitespace, key order or escaping changes the digest.

IDs are opaque, stable strings. Money is a JSON number and currency is an
uppercase ISO 4217 code. Location IDs are the agreed canonical-decimal strings
for the selected environment. Timestamps are RFC 3339 with an explicit
timezone. Request objects use the documented properties; coordinate any
extension with SKUU before sending it.

1. Send order.created

Send one signed event containing the full consumer order and the fulfilment
location selected for each line:

POST {skuu_webhook_url}
Content-Type: application/json
X-SKUU-Signature: sha256=<hmac>

{
  "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": "SKU-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
  }
}

Important rules:

• Send the current full order only when payment_status is paid.
• SKUU routes only paid orders and only lines allocated to the agreed virtual
  SKUU_Network location.
• Every line has a stable line_item_id and variant_id, a positive integer
  quantity, a numeric VAT-inclusive unit_price, and a string
  fulfillment_location_id.
• Include barcode and/or sku when available.
• Orders created through POST /orders carry the skuu_ship tag. Their
  order.created webhook is acknowledged but is not routed again, preventing
  an integration loop.
• Give every logical event a globally unique string event_id.
• An exact transport retry keeps the same event ID, raw body and timestamps.
• HTTP 200 acknowledges the delivery. SKUU confirms durable application and
  replay deduplication during testing.

2. Implement POST /orders

Expose one customer-hosted endpoint that creates exactly one paid, ship-only
order for one shipper. One request may contain multiple lines.

POST {customer_api_root}/orders
Authorization: Bearer <token>
Content-Type: application/json
X-SKUU-Signature: sha256=<hmac>

{
  "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": "SKU-38-BLK",
      "quantity": 1,
      "unit_price": 249.95
    }
  ]
}

Return HTTP 200 with exactly this body shape:

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

Important rules:

• external_ref is the order idempotency key and must be echoed exactly.
• Every line also has its own stable external_ref; preserve it in shipment
  callbacks so repeated variants remain unambiguous.
• order_id is a stable opaque string.
• An identical retry returns the original order and the same success body.
• Reusing an external_ref with a different payload returns HTTP 409 with
  error.code=idempotency_conflict.
• A missing or empty external_ref returns HTTP 400 with
  error.code=invalid_external_ref.
• The injected order is paid, carries the skuu_ship tag and uses standard
  carrier delivery. Pickup and in-store delivery are excluded.
• Supported destination countries are NL, BE and DE.

3. Send fulfillment.shipped

Send one signed event for each shipped package:

POST {skuu_webhook_url}
Content-Type: application/json
X-SKUU-Signature: sha256=<hmac>

{
  "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": "SELLER-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/track/TRACK123",
    "shipment_status": "in_transit"
  }
}

One event represents one package and contains only that package's affected
lines. Connect v1 does not split one order-line quantity across packages.
Multiple packages are supported only when they contain disjoint sets of
complete lines, with a unique fulfillment_id and event_id per package.

fulfillment_id, order_id, created_at, affected line_items,
tracking_number and tracking_company are required. tracking_url is
recommended and shipment_status is optional. Every affected line requires a
stable line_item_id, the original line external_ref, variant_id, and its
positive full ordered quantity. An exact retry keeps the same event ID, raw
body and timestamps.

4. Implement PUT /orders/{order_id}/tracking

Expose a customer-hosted endpoint where SKUU can add seller tracking to the
original consumer order. The path parameter is that original order's opaque
order_id.

PUT {customer_api_root}/orders/{order_id}/tracking
Authorization: Bearer <token>
Content-Type: application/json
X-SKUU-Signature: sha256=<hmac>

{
  "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/track/TRACK123"
}

Return HTTP 200 with exactly this body shape:

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

Important rules:

• Echo external_ref and the URL's order_id exactly.
• external_ref, created_at, a non-empty line_items array,
  tracking_number and tracking_company are required. Each line requires its
  original line_item_id, variant_id and positive full ordered quantity;
  tracking_url is recommended.
• Treat external_ref as the idempotency key. An identical retry returns the
  same success without creating another fulfilment or notification.
• Reusing an external_ref with a different payload returns HTTP 409 with
  error.code=idempotency_conflict.
• A missing or empty external_ref returns HTTP 400 with
  error.code=invalid_external_ref.
• An unknown consumer order returns HTTP 404 with
  error.code=unknown_order and creates no tracking record or notification.
• The customer platform owns the customer shipment notification after
  accepting this write.

Errors and retries

Customer-hosted endpoints return errors in this shape:

{
  "error": {
    "code": "unknown_order",
    "message": "The supplied order_id does not exist"
  }
}

error.code is stable and machine-readable. error.message is diagnostic.

Customer-hosted endpoint response matrix

This matrix applies to POST /orders and
PUT /orders/{order_id}/tracking:

• Retry network failures, HTTP 429 and HTTP 5xx with exponential backoff
  and jitter. Honour a numeric-seconds Retry-After header.
• A retry sends the identical signed body and keeps the same external_ref or
  webhook event_id.
• Do not automatically retry other HTTP 4xx responses.
• Customer webhook senders stop after HTTP 200.

SKUU webhook response matrix

The SKUU-hosted receiver uses these transport responses for
order.created and fulfillment.shipped:

Malformed or unsupported signed events are deliberately acknowledged with
200 so a permanent payload problem cannot create an infinite delivery loop.
SKUU records and exposes the application outcome during the controlled
conformance session.

Testing and activation

SKUU completed its local implementation proof on 2026-08-04. The proof runs
the real Connect receiver, strict wire models and signed outbound client
against an in-memory customer and verifies all four legs without touching a
customer, Supabase, Shopify or a shared environment. The wider focused Phase-2
matrix also verifies atomic persistence, retry safety and financial/status
seams.

Customer activation still follows these controlled steps:

1. Complete and sign off the Phase-1 product and inventory integration.
2. Confirm testing URLs and install the testing credentials.
3. Deploy the customer-hosted endpoints while keeping customer event emission
   and recurring traffic disabled.
4. In a coordinated window, enable only the SKUU inbound receiver and outbound
   writes needed for the synthetic proof.
5. Validate authentication, strict schemas, exact success receipts and each
   webhook's accepted-once/exact-replay behaviour.
6. Prove each customer-hosted write is idempotent: identical replay returns the
   original receipt, changed-payload reuse returns 409, and no duplicate
   order, fulfilment or notification is created.
7. Run one synthetic end-to-end order and fulfilment lifecycle in testing.
8. Disable the exercise traffic and exchange bilateral Phase-2 sign-off.
9. Enable customer event emission, recurring traffic and production only in
   their own separately approved windows.

Until these gates pass, keep recurring deliveries disabled and do not send
production or real-customer traffic.

Cancellation, refunds, delivered-status updates and returns are outside Phase 2
and require the Phase-3 contract or a later addendum.