Building a Modern Fulfillment API

Overview & philosophy

Your warehouse already knows everything an ERP needs: what orders to pick, what stock is on the shelf, and what shipped with which tracking number. An integration API simply exposes those facts over HTTPS in a predictable shape. Get the shape right once and you never build a bespoke integration again — SKU, and every ERP after us, connects the same way.

This guide is written from real integrations. SKU already connects to ShipStation, Starshipit, ShipHero, Shipfusion, Trackstar and Veracore. Every recommendation below is something that made one of those integrations either smooth or painful. We are handing you the smooth path.

The entire surface reduces to three core flows plus a little reference data:

§ Design principles

Seven decisions define whether an integration API is a joy or a liability. Make them once, up front, and apply them everywhere.

§ The integration lifecycle

End to end, a single order travels one loop. The ERP owns the order; you own the warehouse truth; the two reconcile continuously through polling (and, optionally, webhooks).

1. Create. The ERP calls POST /orders with an idempotency key. You persist it, return your real order ID, and the order enters your pick queue.
2. Fulfil. Your warehouse picks, packs and ships — possibly in multiple parcels, possibly split across days.
3. Report shipments. The ERP polls GET /shipments?updated_since=… (and/or you fire a shipment.created webhook). It records each parcel's tracking number and passes it to the sales channel and the end customer.
4. Reconcile inventory. In parallel, the ERP polls GET /inventory?updated_since=… to keep stock counts aligned across channels.
5. Amend or cancel. Before a pick, the ERP can PATCH /orders/{id} to push an address fix or line change — same order ID — or POST /orders/{id}/cancel. Once picking starts, both return a clean 409 so the ERP knows to reconcile rather than assume.

§ Authentication & environments

Per-partner bearer tokens over TLS. Simple, standard, revocable.

Issue each integration partner an API key (ideally a key/secret pair they can rotate). The client sends it on every request as a bearer token:

Authorization: Bearer wms_live_8f2a…c91
Content-Type: application/json
Idempotency-Key: a1b2c3d4-…-e5f6   # on POST /orders only

Two environments, identical shapes

§ Global conventions

Apply these uniformly to every endpoint. Consistency is what lets a partner write one HTTP client and reuse it across all your resources.

Pagination — opaque cursors

Prefer an opaque cursor over page numbers: it survives inserts, doesn't skip or duplicate rows under concurrent writes, and scales to any window size. Every list response carries the same envelope:

{
  "data": [ /* resource objects */ ],
  "pagination": {
    "next_cursor": "eyJpZCI6MTA0MjB9",   # null when no more pages
    "has_more": true
  }
}

The client passes ?cursor=eyJpZCI6MTA0MjB9 back to fetch the next page, and stops when has_more is false.

Timestamps & money

Errors — one envelope, correct status codes

Return the right HTTP status and a machine-readable body. A partner should be able to branch on error.code without string-matching a message.

{
  "error": {
    "code": "invalid_warehouse",
    "message": "warehouse_id 'wh_zzz' is not a known warehouse.",
    "field": "warehouse_id",
    "request_id": "req_01J8…"          # echo back for support
  }
}

Rate limits

Advertise your limits in headers so well-behaved clients self-throttle:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1782043260       # unix epoch
Retry-After: 30                   # only on a 429

1 · Orders — inbound (ERP → you) Must have

The ERP creates a fulfillment order: who to ship to, what to ship, from which warehouse, by which method. You accept it, assign your order ID, and own it through to shipment.

Create a fulfillment order. The client sends an Idempotency-Key header; if you've seen it before, return the existing order (HTTP 200) instead of creating a second.

{
  "order_number": "SO-100423",          # the ERP's human-facing order #
  "reference": "F-100423-1",            # ERP's unique fulfillment ref (dedup anchor)
  "order_date": "2026-07-02T09:15:00Z",
  "warehouse_id": "wh_syd_1",         # one of YOUR warehouse ids (§4)
  "shipping_method_id": "sm_auspost_express", # or "shipping_method": "Express"
  "signature_required": false,
  "insurance": false,
  "gift_message": null,
  "packing_note": "Leave in porch",
  "ship_to": {
    "name": "Jane Doe",
    "company": "Acme Pty Ltd",
    "email": "[email protected]",
    "phone": "+61 400 123 456",
    "address1": "123 Main St",
    "address2": null,
    "city": "Sydney",
    "state": "NSW",
    "postcode": "2000",
    "country": "AU"                   # ISO-3166 alpha-2
  },
  "items": [
    {
      "sku": "WIDGET-BLUE-M",
      "description": "Blue Widget — Medium",
      "quantity": 2,
      "unit_price": "19.99",
      "currency": "AUD"
    }
  }]
}

Request fields

Response — 201 Created

{
  "id": "ord_8Kd92m",            # YOUR order id — the ERP stores this forever
  "order_number": "SO-100423",
  "reference": "F-100423-1",
  "status": "received",
  "warehouse_id": "wh_syd_1",
  "created_at": "2026-07-02T09:15:04Z",
  "shipments": []                  # populated as parcels ship
}

Retrieve a single order with its current status and any shipments so far. Also support GET /v1/orders?updated_since=…&cursor=… for bulk reconciliation.

Cancel an order that hasn't shipped. Return 200 with "status": "cancelled" if you caught it in time, or 409 Conflict if it already shipped — so the ERP knows to stop and reconcile rather than assume success.

{ "id": "ord_8Kd92m",
  "status": "cancelled" }

{ "error": {
   "code": "already_shipped",
   "message": "Order has shipped." }}

Order details change constantly — a customer corrects their address, adds an item, or upgrades to express after the order is placed but before the box is packed. A single amend endpoint lets the ERP push only what changed and keep the same order ID, instead of cancelling and re-creating. Send just the changed fields; for line items, send the full desired items[] set — it replaces the existing lines (so removing a line = omit it, reduce a quantity = send the new number).

{
  "shipping_method_id": "sm_auspost_express",   # upgraded to express
  "ship_to": {
    "name": "Jane Doe",
    "address1": "456 New Street",          # corrected address
    "address2": "Unit 5",
    "city": "Sydney", "state": "NSW",
    "postcode": "2010", "country": "AU"
  },
  "items": [                               # full desired line set — replaces existing
    { "sku": "WIDGET-BLUE-M", "quantity": 1 },   # qty 2 → 1
    { "sku": "WIDGET-RED-S",  "quantity": 3 }    # new line added
  ]
}

Include an If-Match: "<version>" header carrying the order's current version so two concurrent edits can't silently clobber each other — return 409 if the version has already moved on. Fields you don't send are left untouched.

What can be amended — while the order hasn't been picked

Response — 200 OK if in time, 409 if too late

{ "id": "ord_8Kd92m",
  "status": "received",
  "version": "4",            # bumped
  "updated_at": "2026-07-02T10:02:00Z" }

{ "error": {
   "code": "too_late_to_amend",
   "message": "Order is being picked; cancel to change it.",
   "order_status": "processing" }}

2 · Shipments — outbound (you → ERP) Must have

This is the flow that matters most, and the one most APIs get wrong. When goods leave your dock, the ERP needs the tracking number(s) — fast, cheaply, and one entry per parcel. Model this well and everything downstream (customer notifications, channel updates, cost reconciliation) just works.

Return shipments created or updated since a timestamp, newest changes last, in stable order, paginated by cursor. A shipment belongs to an order and carries one tracking number per physical parcel.

{
  "data": [
    {
      "id": "shp_a1B2c3",
      "order_id": "ord_8Kd92m",           # the order this fulfils
      "order_number": "SO-100423",
      "status": "shipped",
      "warehouse_id": "wh_syd_1",
      "shipped_at": "2026-07-02T22:04:11Z",
      "created_at": "2026-07-02T22:04:11Z",
      "updated_at": "2026-07-02T22:04:11Z",
      "cost": { "amount": "12.40", "currency": "AUD" },
      "voided": false,
      "parcels": [                          # ← one entry per physical box
        {
          "tracking_number": "ABC123456789AU",
          "tracking_url": "https://auspost.com.au/track/ABC123456789AU",
          "carrier": "auspost",
          "service": "Express Post",
          "weight": { "value": 1.2, "unit": "kg" },
          "dimensions": { "length": 30, "width": 20, "height": 10, "unit": "cm" }
        },
        {
          "tracking_number": "ABC123456790AU",       # same order, 2nd box, own tracking #
          "tracking_url": "https://auspost.com.au/track/ABC123456790AU",
          "carrier": "auspost",
          "service": "Express Post"
        }
      ],
      "items": [                            # what physically shipped, for per-line fulfilment
        { "sku": "WIDGET-BLUE-M", "quantity": 2 }
      ]
    }
  ],
  "pagination": { "next_cursor": null, "has_more": false }
}

Shipment fields

3 · Inventory — outbound (you → ERP) Must have

Stock the ERP can trust, broken out per warehouse. A SKU isn't a single number — it's on the shelf in Sydney and Melbourne in different quantities, some available, some already allocated to open orders.

Return stock levels per SKU. Each SKU carries a warehouses[] breakdown so the ERP can decide sourcing and surface accurate availability per channel.

{
  "data": [
    {
      "sku": "WIDGET-BLUE-M",
      "updated_at": "2026-07-02T22:05:00Z",
      "warehouses": [                     # ← per-warehouse breakout
        {
          "warehouse_id": "wh_syd_1",
          "on_hand": 120,              # physically present
          "available": 96,             # sellable now (on_hand − allocated)
          "allocated": 24,             # reserved for open orders
          "incoming": 0,               # inbound / on a PO to you
          "backordered": 0
        },
        {
          "warehouse_id": "wh_mel_1",
          "on_hand": 40, "available": 40, "allocated": 0, "incoming": 30, "backordered": 5
        }
      ]
    }
  ],
  "pagination": { "next_cursor": null, "has_more": false }
}

4 · Warehouses & shipping methods Must have

Two small, slow-changing lists the ERP fetches occasionally and maps against once. They let orders reference stable IDs instead of guessing at free-text.

{ "data": [{
  "id": "wh_syd_1",
  "name": "Sydney DC",
  "code": "SYD",
  "address": {
    "address1": "1 Freight Rd",
    "city": "Sydney", "state": "NSW",
    "postcode": "2000", "country": "AU"
  }
}]}

{ "data": [{
  "id": "sm_auspost_express",
  "name": "Express Post",
  "carrier": "auspost",
  "carrier_name": "Australia Post",
  "service_code": "EXP"
},{
  "id": "sm_auspost_parcel",
  "name": "Parcel Post",
  "carrier": "auspost", "service_code": "PP"
}]}

The ERP maps its own warehouses and shipping options to these IDs once, then references them on every order. Stable IDs here save a class of "unknown method" errors later.

5 · Advanced flows — the full inventory lifecycle Nice to have

The three core flows cover the order → ship → stock loop. As the integration matures, these let the ERP manage the whole inventory lifecycle through you — receiving inbound stock, reconciling adjustments, and handling returns. Each reuses the exact same conventions (updated_since polling, cursors, UTC, one error envelope), so they're incremental to build and none is required to launch.

Nice to have  5a · Inbound shipments & ASNs — ERP → you, then you → ERP

The ERP notifies you that stock is on its way (an Advanced Shipment Notice); you receive it and report what actually arrived — including over-, under- and damaged-delivery discrepancies. This closes the loop on replenishment.

{
  "reference": "ASN-5567",            # ERP's PO / ASN reference
  "warehouse_id": "wh_syd_1",
  "expected_at": "2026-07-08",
  "supplier": "Acme Manufacturing",
  "items": [
    { "sku": "WIDGET-BLUE-M", "expected_quantity": 500 },
    { "sku": "WIDGET-RED-S",  "expected_quantity": 300 }
  ]
}
# → { "id": "ib_9932", "status": "expected" }

Once you receive the goods, the record updates with the received quantities and any discrepancy:

{ "data": [{
  "id": "ib_9932",
  "reference": "ASN-5567",
  "status": "received",            # expected → partially_received → received
  "received_at": "2026-07-08T03:12:00Z",
  "warehouse_id": "wh_syd_1",
  "items": [
    { "sku": "WIDGET-BLUE-M", "expected_quantity": 500, "received_quantity": 498, "discrepancy": -2 },
    { "sku": "WIDGET-RED-S",  "expected_quantity": 300, "received_quantity": 300, "discrepancy": 0 }
  ]
}]}

Nice to have  5b · Inventory adjustments — you → ERP

Not every stock change comes from an order. Damage, cycle-count corrections, found or lost stock — the ERP needs the reason a number moved, not just the new total, to keep its own ledger honest and to audit shrinkage.

{ "data": [{
  "id": "adj_4471",
  "sku": "WIDGET-BLUE-M",
  "warehouse_id": "wh_syd_1",
  "quantity_delta": -3,              # signed: negative = removed
  "reason": "damaged",              # damaged | cycle_count | lost | found | expired
  "note": "Water damage, pallet 12",
  "adjusted_at": "2026-07-02T05:00:00Z"
}]}

Nice to have  5c · Customer returns / RMAs — you → ERP (optionally ERP → you)

When goods come back to your warehouse, the ERP needs to know what returned, in what condition, and whether it went back on the shelf — so it can refund, restock, or write off. Optionally, the ERP pre-authorizes an expected return via POST /v1/returns (an RMA); either way you report what you receive.

{ "data": [{
  "id": "ret_2201",
  "order_id": "ord_8Kd92m",          # the original order
  "order_number": "SO-100423",
  "rma": "RMA-100423",
  "status": "received",            # expected → received → processed
  "received_at": "2026-07-10T22:00:00Z",
  "warehouse_id": "wh_syd_1",
  "items": [
    { "sku": "WIDGET-BLUE-M", "quantity": 1, "condition": "resellable", "restocked": true },
    { "sku": "WIDGET-RED-S",  "quantity": 1, "condition": "damaged",    "restocked": false }
  ]
}]}

Advanced-flow endpoints at a glance

§ Efficient incremental polling Must have

Polling done right is quiet and cheap. The pattern is a high-water mark: the client remembers the last change it saw and asks only for what's newer.

The loop

1. Client stores a cursor/timestamp of the last shipment it processed — say 2026-07-02T22:04:11Z.
2. It calls GET /shipments?updated_since=2026-07-02T22:04:11Z.
3. It walks pages via next_cursor until has_more is false.
4. It advances its high-water mark to the newest updated_at it saw, and sleeps until the next tick.

Recommended default cadence: poll /shipments every 2–5 minutes, /inventory every 15–30 minutes. If you add webhooks (next section), these polls become a cheap safety net rather than the primary mechanism.

§ Webhooks — optional, recommended Nice to have

Webhooks turn minutes of polling latency into seconds by pushing events to the ERP as they happen. They are an optimisation on top of polling — never a replacement for it. Build the polling API first; add webhooks when you're ready.

Event catalog

Delivery payload

{
  "event_id": "evt_01J8XQ…",       # unique & stable — the client's dedup key
  "event_type": "shipment.created",
  "created_at": "2026-07-02T22:04:12Z",
  "data": { /* the full shipment object from §2 */ }
}

Signing — HMAC-SHA256 over the raw body

Sign every webhook so the ERP can prove it came from you and wasn't tampered with. Send a signature header computed over the exact raw request bytes plus a timestamp:

X-Webhook-Signature: t=1782043452,v1=5d41402abc4b2a76b9719d911017c592…

# where v1 = hex( HMAC_SHA256( secret, "{t}.{raw_request_body}" ) )

Reliability — retries & idempotency

• Retry with backoff on any non-2xx (e.g. after 10s, 1m, 5m, 30m, then hourly for a day). Networks blip; a single delivery attempt loses events.
• Stable event_id so the client can dedup — retries and at-least-once delivery mean the same event can arrive twice. The client stores seen IDs; you just keep the ID constant across retries.
• Deliveries can arrive out of order. The client should treat webhooks as "something changed, here's the latest state," and always be able to fall back to a poll.

Subscription management

Let a partner register their endpoint via API (or your dashboard). Keep it minimal:

{
  "url": "https://erp.example.com/webhooks/wms/wh_9f2a…",
  "events": [ "shipment.created", "shipment.updated", "order.cancelled" ]
}
# → returns { "id": "whk_…", "secret": "whsec_…" }  ← the HMAC secret, shown once

Pair with GET /v1/webhooks and DELETE /v1/webhooks/{id}. Generate the signing secret server-side and reveal it once on creation.

§ MVP & rollout plan

You don't need all of this to go live. Here's the smallest surface that unblocks a full integration — then the polish, in priority order.

§ Appendix — status vocabularies

Small, closed enumerations the ERP can map with confidence. Pick names and don't change them.