Public API Order Hub — Orders & Order Lines Guide

How to manage orders and their line items on the Retraced platform via the Public API.

The Order Hub exposes orders and their line items:

1. Orders (/api/v2/orders) — the commercial document: order number, buyer, supplier, dates, status, and its line items.
2. Order lines (/api/v2/order-lines) — the line items on an order (which style, how much, in what unit), exposed read-only (GET only).

An order line only ever exists as part of an order, so all line writes happen through the order: create lines nested in POST /orders, and add/change/remove them later with PATCH /orders/:id. Deleting an order deletes its lines. You read lines back via the GET /order-lines endpoints.

Migration note: the previous POST / PATCH / DELETE /api/v2/order-lines endpoints have been removed. Manage lines via the order endpoints described below. The GET line endpoints are unchanged.

Setup

# Base URL
BASE_URL="https://publicapi.retraced.com/api/v2"

# Authentication — use your company API key
API_KEY="your-company-api-key"

All examples use curl. The API key is passed via the companyapikey header. Every operation is scoped to the company the API key belongs to — you can only see and manage your own orders.

Orders

Create an order

curl -X POST "$BASE_URL/orders" \
  -H "companyapikey: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderNumber": "PO-2026-0042",
    "status": "IN_PROGRESS",
    "orderSubType": "STANDARD",
    "source": "ERP",
    "tags": ["priority"],
    "buyerCompanyId": "<buyer-company-id>",
    "supplierCompanyId": "<supplier-company-id>",
    "receiverCompanyId": "<receiver-company-id>",
    "vendorCompanyId": "<vendor-company-id>",
    "factory": "<factory-company-id>",
    "buyerFacilityProcess": "Quality inspection",
    "supplierFacilityProcess": "Weaving",
    "receiverFacilityProcess": "Washing & finishing",
    "orderDate": "2026-07-01",
    "deliveryDate": "2026-09-15",
    "agreedDeliveryDate": "2026-09-10",
    "expectedShippingDate": "2026-08-28",
    "shippingDate": "2026-08-30",
    "expectedDeliveryDate": "2026-09-15",
    "shipmentReference": "SHIP-2026-0042",
    "internalResponsiblePersons": ["<user-id-or-email>"],
    "season": "FW26",
    "counterpartyOrderNumberRef": "WW-SO-2026-118",
    "lines": [
      {
        "orderLineNumber": "PO-2026-0042-PACKAGING",
        "styleId": "<style-id>",
        "quantity": 300,
        "unit": "PIECES",
        "secondaryQuantity": 120.5,
        "secondaryUnit": "KILOGRAM"
      }
    ]
  }'

Only orderNumber, buyerCompanyId and supplierCompanyId are required — every other field can be omitted. Nested lines are created atomically with the order and are returned in the create response (and on GET /orders/:id), each carrying its server-assigned id and lineNo.

• The order owner must be a party to the order: your authenticated company must be the buyerCompanyId or the supplierCompanyId, otherwise the request is rejected with 400 (code order_owner_not_party).
• Receiver defaults to the buyer: if you omit receiverCompanyId, it defaults to buyerCompanyId (and receiverFacilityProcess defaults to buyerFacilityProcess). If you send one of receiverCompanyId / receiverFacilityProcess you must send both (400 otherwise) — this pairing rule applies on create only.
• orderType and tracingStatus may be present in the body for convenience but are ignored — both are computed by the server.

Request body fields:

orderType is computed by the server — you never send it. It is derived from how the buyer/supplier relate to your (authenticated) company: you are the buyer → PURCHASE_ORDER, you are the supplier → SALES_ORDER, you are both → INTERNAL_ORDER.

Response (200):

{
  "metadata": { "success": true },
  "data": {
    "id": "order_01KWHF7TD318JZA3KM9A9E9979",
    "forCompanyId": "<your-company-id>",
    "orderNumber": "PO-2026-0042",
    "orderType": "PURCHASE_ORDER",
    "orderSubType": "STANDARD",
    "status": "IN_PROGRESS",
    "tags": ["priority"],
    "source": "ERP",
    "buyerCompanyId": "<buyer-company-id>",
    "supplierCompanyId": "<supplier-company-id>",
    "receiverCompanyId": "<receiver-company-id>",
    "vendorCompanyId": "<vendor-company-id>",
    "factory": "<factory-company-id>",
    "buyerFacilityProcess": "Quality inspection",
    "supplierFacilityProcess": "Weaving",
    "receiverFacilityProcess": "Washing & finishing",
    "orderDate": "2026-07-01",
    "deliveryDate": "2026-09-15",
    "agreedDeliveryDate": "2026-09-10",
    "expectedShippingDate": "2026-08-28",
    "shippingDate": "2026-08-30",
    "expectedDeliveryDate": "2026-09-15",
    "actualDeliveryDate": null,
    "shipmentReference": "SHIP-2026-0042",
    "internalResponsiblePersons": ["<user-id>"],
    "internalResponsiblePerson": "<user-id>",
    "season": "FW26",
    "counterpartyOrderNumberRef": "WW-SO-2026-118",
    "isArchived": false,
    "tracingStatus": null,
    "createdAt": "2026-07-02T10:30:00.000Z",
    "createdByApiKeyId": "<api-key-id>",
    "updatedAt": "2026-07-02T10:30:00.000Z",
    "lineCount": 1,
    "lines": [
      {
        "id": "ordline_01KWHF7XAY4Q74CAVXYAPJ6FJV",
        "orderLineNumber": "PO-2026-0042-PACKAGING",
        "lineNo": 1,
        "styleId": "<style-id>",
        "quantity": 300,
        "unit": "PIECES",
        "secondaryQuantity": 120.5,
        "secondaryUnit": "KILOGRAM",
        "tracingReflectionOrderId": null,
        "tracingOrderRequestedAt": null
      }
    ]
  }
}

(Response trimmed — every order also carries full createdBy* / updatedBy* audit fields. Fields you never sent come back as null; tracingStatus is system-computed and read-only.)

• internalResponsiblePerson (singular) is a deprecated read-only mirror of internalResponsiblePersons[0] (or null when there are none); prefer the array.
• lineCount is the number of lines on the order. lines is the full nested line array on POST /orders and GET /orders/:id, but is always [] on GET /orders (list) — use GET /order-lines?orderId=... to page a list's lines.

Store data.id — you need it to manage order lines and for later updates. Order ids are server-generated with an order_ prefix (order lines use ordline_); treat them as opaque strings.

The party fields (who's who)

An order carries up to five company references. Only buyer and supplier are required and enforced (your company must be one of them); the rest are optional descriptive parties. How brands typically use them:

The *FacilityProcess fields (buyerFacilityProcess, supplierFacilityProcess, receiverFacilityProcess) are free-text labels for the process each party performs — they are descriptive, not validated against a list.

These are conventions, not rules the platform enforces. Retraced only checks that your company is the buyer or supplier and that the receiver pair is supplied together (see Create an order); it assigns no other meaning to these fields.

Order status

status (IN_PROGRESS, IN_REVIEW, COMPLETED) is not tied to any Retraced workflow — the platform never acts on it or transitions it for you. Use it to carry whatever state your own process needs.

Date fields

Business dates (orderDate, agreedDeliveryDate, deliveryDate, …) are calendar dates in YYYY-MM-DD with no time or timezone, stored and returned verbatim; createdAt / updatedAt are ISO 8601 UTC timestamps set by the server. See Dates & time for the full rules.

Archiving vs. deleting

An order can be archived (reversible) or deleted (permanent) — they are different:

• Archive via "isArchived": true on PATCH /orders/:id (unarchive with false). The order and its lines are kept intact but drop out of the default list and are excluded from the analytics and reporting views in the Retraced platform. Filter with isArchived=true / false; omit the parameter to list both archived and active orders.
• Delete via DELETE /orders/:id is a hard delete — the order and all its lines are permanently removed and can't be recovered.

List orders

curl "$BASE_URL/orders?page=1&limit=20&sort=updatedAt&order=DESC&status=IN_PROGRESS" \
  -H "companyapikey: $API_KEY"

Query parameters:

Deleted orders are physically removed and never returned.

Response (200):

{
  "metadata": {
    "success": true,
    "pagination": { "page": 1, "limit": 20, "total": 42, "totalPages": 3 }
  },
  "data": [ { "id": "order_01KWHF7TD318JZA3KM9A9E9979", "orderNumber": "PO-2026-0042", "...": "..." } ]
}

Fetch, update, delete

# Fetch one order
curl "$BASE_URL/orders/<order-id>" -H "companyapikey: $API_KEY"

# Partial update — send only the fields you want to change
curl -X PATCH "$BASE_URL/orders/<order-id>" \
  -H "companyapikey: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "COMPLETED", "actualDeliveryDate": "2026-09-12" }'

# Delete (hard — also deletes the order's lines)
curl -X DELETE "$BASE_URL/orders/<order-id>" -H "companyapikey: $API_KEY"

• PATCH has partial semantics: omitted fields keep their value. Nullable fields (dates, source, season, party IDs, …) can be cleared by sending null. You can also archive/unarchive via "isArchived": true|false.
• Sending a lines array reconciles the order's lines — see Update an order's lines.
• Changing orderNumber — or changing buyerCompanyId/supplierCompanyId in a way that re-derives the order type — returns 400 (code order_number_already_existing) if the number is already taken in the resulting (company, order type) group.
• DELETE is a hard delete (returns 204): the order and all of its lines are permanently removed — this cannot be undone. Deleting an already-deleted or foreign order returns 404.
• Tracing side-effects: if the order (or any of its lines) is part of a tracing chain, a PATCH re-syncs the linked tracing orders and notifies the counterparty, and a DELETE cascades to remove the counterparty's mirrored tracing data. Nested styleIds must reference a non-archived style your company owns, otherwise the write is rejected.

Update an order's lines

Send a lines array on PATCH /orders/:id to declaratively full-sync the order's lines — the array is the desired final set:

• an entry with an id updates that existing line (only the fields you include change);
• an entry without an id creates a new line (styleId, quantity, unit are then required);
• any existing line absent from the array is deleted.

Omitting lines entirely leaves the order's lines untouched. Because omission means deletion, always send the complete current set of lines you want to keep — fetch them first via GET /order-lines?orderId=....

curl -X PATCH "$BASE_URL/orders/<order-id>" \
  -H "companyapikey: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "IN_REVIEW",
    "lines": [
      { "id": "ordline_01KWHF7XAY4Q74CAVXYAPJ6FJV", "quantity": 1750 },
      { "id": "ordline_01KWHF7YSW1A1R34E1DMEHMAK5", "secondaryQuantity": null },
      { "styleId": "<style-id>", "quantity": 250, "unit": "PIECES" }
    ]
  }'

In the example the first line is updated, the second clears its secondary quantity (which also clears secondaryUnit), a third line is created, and any other existing line is deleted. The order's scalar fields and its lines are reconciled atomically — if any line fails (e.g. a duplicate orderLineNumber, 409), the whole PATCH rolls back. A bare { "id": "..." } entry keeps that line unchanged (its audit fields are not touched). Fetch the resulting lines with GET /order-lines?orderId=....

See the order line fields for the accepted per-line properties.

Order lines (read-only)

Order lines are created, updated, and deleted only through their parent order (see Create an order and Update an order's lines). Over the Public API they are exposed read-only.

Order line fields

The per-line object used inside a create/update lines array:

lineNo is assigned by the server (1, 2, 3, … per order) and never accepted as input. New lines continue numbering after the order's existing lines. An orderLineNumber that already exists on the order — or that appears twice in one request — returns 409 with code order_not_unique, and the whole write rolls back.

Unit values

unit accepts the unit enum below. Any other value is rejected with 400.

List order lines

# Lines of one order
curl "$BASE_URL/order-lines?orderId=<order-id>&page=1&limit=20" \
  -H "companyapikey: $API_KEY"

# All lines across all your orders (omit orderId)
curl "$BASE_URL/order-lines?page=1&limit=100" -H "companyapikey: $API_KEY"

Pagination works exactly like orders (page 1-based, limit 1–100 default 20, same metadata.pagination envelope). Lines of deleted orders are never returned.

Each line additionally carries two read-only tracing fields — tracingReflectionOrderId (the tracing order this line is reflected into, or null) and tracingOrderRequestedAt (null until tracing is requested) — plus an embedded order summary object (id, orderNumber, orderType, buyerCompanyId, supplierCompanyId, orderDate, updatedAt, updatedByUserName, tracingStatus, tags, source, season). The order object is populated on the list endpoint and is null on GET /order-lines/:lineId.

Fetch a single line

curl "$BASE_URL/order-lines/<line-id>" -H "companyapikey: $API_KEY"

Returns the line (with full audit fields), or 404 when the line does not exist, belongs to another company, or its parent order has been deleted.

End-to-end example

# 1. Create the order together with its two lines — one atomic request
ORDER_ID=$(curl -s -X POST "$BASE_URL/orders" \
  -H "companyapikey: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "orderNumber": "PO-2026-0042",
    "buyerCompanyId": "<buyer-company-id>",
    "supplierCompanyId": "<supplier-company-id>",
    "lines": [
      {"styleId": "<style-id-1>", "quantity": 1500, "unit": "PIECES"},
      {"styleId": "<style-id-2>", "quantity": 800, "unit": "PIECES"}
    ]
  }' | jq -r '.data.id')

# 2. Read the order's current lines (you need their ids to keep them on the next PATCH)
LINES=$(curl -s "$BASE_URL/order-lines?orderId=$ORDER_ID&limit=100" \
  -H "companyapikey: $API_KEY" | jq -c '[.data[] | {id}]')

# 3. Add a third line while keeping the existing two (full-sync PATCH)
curl -s -X PATCH "$BASE_URL/orders/$ORDER_ID" \
  -H "companyapikey: $API_KEY" -H "Content-Type: application/json" \
  -d "{\"lines\": $(echo "$LINES" | jq -c '. + [{"styleId": "<style-id-3>", "quantity": 250, "unit": "PIECES"}]')}"

# 4. List the order's lines again
curl -s "$BASE_URL/order-lines?orderId=$ORDER_ID" -H "companyapikey: $API_KEY"

Common errors