System API destinations

System API destinations

Ask the team that owns your receiving system to confirm its endpoint, accepted
request format, authentication, dry-run handling and duplicate protection.
These settings describe their API; Twelfth does not invent the endpoint.

For native Retail Express prices and end-of-life updates, use
Retail Express → Writeback. The setup
below is for an endpoint your team provides, such as an order bridge; its
Retail Express preset does not enable native purchase-order or transfer writes.

Add a destination → Your system’s API. Twelfth itself calls your system’s
endpoint with your credential when a decision lands, and records the reference
it returns. The system can be Retail Express (hosted, self-hosted or through a
bridge your IT runs) or any other. If the kind is greyed out with Not configured in this
environment, this environment cannot hold credentials yet; ask Twelfth.

  1. Preset. Where Twelfth already reads the workspace’s Retail Express,
    Retail Express fills the system name, the purchase-order path and the
    API-key header; Custom starts blank. Elsewhere there is no preset to
    choose: every system starts blank.
  2. System and Base URL: the name shown on the card and everywhere else
    (Retail Express, Cin7, Our order bridge), and the endpoint the paths
    are added to, for example https://integrations.example.com.au/retail-express.
  3. Paths, one per kind: orders, prices, transfers and product updates. At
    least one is required; a kind with no path is not sent here.
  4. Auth: None, API key (header name, default x-api-key), Bearer, or
    Basic (user:password). The credential is stored encrypted and never shown
    again. When editing, leave it blank to keep the stored one.
  5. Requests: Per decision (a purchase order with its lines) or Per line.
    Body: Twelfth envelope (below) or Mapped fields only, which sends exactly the
    columns you mapped, one object per line, as { "lines": [...] } when
    grouped per decision. Reference path: where the reference sits in the
    reply, as a dot path such as id or purchaseOrder.id. A map keyed by Twelfth line
    ID at that path also works.

Check the endpoint and test request

  • Check calls the base URL with the credential and answers in one line:
    Reachable · credential accepted · 210 ms, or what went wrong. A 401 or
    403 reads credential refused.
  • Send a test order POSTs a sample request to the kind’s path with
    X-Twelfth-Dry-Run: true and shows the reply compactly, with every path in
    it that could be a reference as a chip. Click a chip to set the reference
    path; the one Twelfth suggests is marked. This sends a real HTTP request: your endpoint must honour the dry-run
    header and avoid creating records. Confirm that behaviour with your technical
    team before using this button.

Neither button saves anything.

Request format for your technical team

One JSON purchase order per decision (or per line), to the path for its kind,
with the Twelfth envelope body:

{
  "twelfthDecisionId": "…",
  "kind": "purchase_order",
  "supplier": "Mattel",
  "supplierKey": "mattel",
  "sourceSupplierId": "1842",
  "buyerScope": "Toys",
  "decidedBy": "sam@example.com",
  "decidedAt": "2026-10-14T15:10:00+11:00",
  "rationale": "…",
  "links": { "decision": "https://…", "project": "https://…" },
  "lines": [
    {
      "lineId": "…",
      "decisionId": "…",
      "kind": "purchase_order",
      "fields": { "ProductId": "10234", "ManufacturerSKU": "ABC-123", "Qty": 24, "…": "…" },
      "sourceProductId": "10234",
      "sku": "ABC-123",
      "supplierSku": "MAT-ABC-123",
      "productName": "…",
      "quantity": 24,
      "unitCostEx": 12.5,
      "price": null,
      "requiredBy": "2026-10-14",
      "lane": null,
      "line": { "twelfth": { "…": "…" }, "source": { "…": "…" }, "decision": { "…": "…" } }
    }
  ]
}

The example time uses +11:00 for Melbourne AEDT.

fields is the line in the columns you mapped (the Retail Express purchase
orders preset gives the bulk-upload names); line is the whole line. Every
request carries an Idempotency-Key. Your endpoint must use it to deduplicate
requests so a retry does not raise the same order twice.

A 2xx reply with a reference at the reference path marks every line in the
request acknowledged, with that reference as its purchase order number. A
2xx without one is delivered; the lines wait for a reference. A 401 or
403 loses the connection: nothing further is attempted and the card says
Retail Express refused the credential. Update the API key or token. Edit the
destination and enter the new one; delivery resumes on the next trigger or with
Deliver now. Any other non-2xx is a failed attempt, retried on the
schedule below.

Product updates

An endpoint can receive product-update decisions if Product updates is
selected in the filter and its path is configured. The Twelfth envelope
includes the selected product field, value and reason code. Your endpoint must
understand those fields and apply the intended change. A default order-only
Rex preset does not set up that path.

Previous Spreadsheets Next Webhooks