Getting Started & Integration FAQ

The conventions that apply across the whole Retraced Public API — authentication, the response envelope, pagination, dates, versioning, and the questions integrators ask most often. Read this once before building; the resource guides (Products, Orders, Materials, …) then only cover what is specific to them.

Authentication

The API is authenticated with an API key, passed in the companyapikey request header. There is no OAuth flow and no per-request signing.

curl "https://publicapi.retraced.com/api/v2/styles?level=style" \
  -H "companyapikey: your-api-key"

To create a key, log in to the Retraced Platform and go to Developers HQ → API Keys → Create. Copy the key somewhere safe — it is shown only once and cannot be retrieved again. If you don't see Developers HQ in the sidebar, ask your Customer Success Manager to enable it.

• The key is scoped to a single company. Every request is automatically limited to that company's data — you only ever see and manage your own records.
• No IP allow-listing is required. You can call the API from any host.

Shell gotcha: if your key contains $ characters, wrap it in single quotes so the shell doesn't expand them: -H 'companyapikey: $2b$10$...'. Double quotes turn $2b into an empty string and you get a 401.

Environments

Your API key works against both environments.

The response envelope

Every response — success or error — uses the same envelope: a metadata object plus a data payload.

Success:

{
  "metadata": { "success": true },
  "data": { }
}

List success — metadata also carries pagination:

{
  "metadata": {
    "success": true,
    "pagination": { "page": 1, "limit": 20, "total": 42, "totalPages": 3 }
  },
  "data": [ ]
}

Error — metadata.success is false, and the body carries a numeric statusCode, a stable machine-readable code, and a human-readable message:

{
  "metadata": { "success": false },
  "statusCode": 404,
  "code": "not_found",
  "message": "Resource not found"
}

Branch your error handling on statusCode (or the stable code string) — never on the message text, which may change.

Common errors

Pagination, sorting & incremental sync

List endpoints are paginated with 1-based page numbers.

• page — 1-based; defaults to 1.
• limit — page size. Most endpoints default to 20 and cap at 100. A few differ: /companies defaults to 50 (max 500) and /certificates allows up to 500. Check each endpoint's limit parameter in the API Reference.
• sort / order — sort column and direction (ASC / DESC); the accepted sort columns vary per endpoint.

Page through a full result set until page reaches metadata.pagination.totalPages:

page=1
while : ; do
  resp=$(curl -s "https://publicapi.retraced.com/api/v2/styles?level=style&page=$page&limit=100" \
    -H "companyapikey: $API_KEY")
  echo "$resp" | jq '.data[]'
  total=$(echo "$resp" | jq '.metadata.pagination.totalPages')
  [ "$page" -ge "$total" ] && break
  page=$((page + 1))
done

Incremental sync

Endpoints that expose updatedAfterUnixMs (and updatedBeforeUnixMs) let you pull only what changed since your last sync instead of re-fetching everything. The value is a Unix timestamp in milliseconds (not seconds):

# Everything updated since 2026-07-01T00:00:00Z
curl "https://publicapi.retraced.com/api/v2/orders?updatedAfterUnixMs=1782777600000" \
  -H "companyapikey: $API_KEY"

Store the largest updatedAt you have seen and pass it as updatedAfterUnixMs on the next run.

Rate limits

Last updated: 2026-07-27.

The API does not currently enforce a rate limit - there is no fixed request quota. Retraced will introduce limits in the future, so build your client to be ready for it:

• Prefer incremental sync over re-pulling entire datasets.
• Treat 429 Too Many Requests as a retryable, transient response: back off (exponentially) and retry rather than failing the job.

Building this in now means a future limit won't break your integration.

Dates & time

Two kinds of date fields exist, and they behave differently:

• Business dates (e.g. orderDate, agreedDeliveryDate, deliveryDate, shippingDate) are calendar dates in YYYY-MM-DD form with no time and no timezone. They are stored and returned exactly as written — 2026-07-01 always reads back as 2026-07-01, regardless of the reader's timezone.
• System timestamps (createdAt, updatedAt) are full ISO 8601 UTC date-times (e.g. 2026-07-02T10:30:00.000Z), set by the server. Use these for incremental sync.

On write, business-date fields are validated as YYYY-MM-DD; in responses they come back as plain strings. Send exactly YYYY-MM-DD — a full date-time is rejected with a 400.

Pull model — no webhooks

The API is pull-only. There are no webhooks or server push, so Retraced will not call your systems when data changes. To stay in sync, poll on a schedule that suits your use case and use incremental sync to keep each poll cheap:

1. Run a periodic job (e.g. hourly or daily).
2. Request each resource with updatedAfterUnixMs set to the last sync's high-water mark.
3. Persist the largest updatedAt you saw for the next run.

Archiving vs. deleting

These are two different operations — know which one an endpoint gives you:

• Archiving (isArchived) is a reversible soft state. Archived records stay in the system and keep all their data, but drop out of the default lists and are excluded from the analytics and reporting views in the Retraced platform. You unarchive to restore them. On resources that support it, filter with isArchived=true to see archived records and isArchived=false for active ones (omit the parameter on /orders to get both; on /styles the default is active-only).
• Deleting is permanent. Where an endpoint exposes DELETE (for example DELETE /orders/:id), the record — and its children — are hard-deleted and cannot be recovered. A deleted record simply returns 404 afterwards.

Prefer archiving when you might need the record back; delete only when you are certain.

API versions

The current API is v2, served under /api/v2. The interactive API Reference also carries v0 and v1 specifications (switch between them with the source selector at the top of the page) — these are legacy and kept only for existing integrations. Build new integrations on v2.

Write conventions

• Prefer omitting an optional field over sending null. On several resources null is meaningful: it clears a value, and on products (styles/variants/SKUs) setting an inheritable field to null re-enables inheritance from the parent. If you don't intend to change a field, leave it out of the request body entirely.
• Some updates replace, not merge. A few write endpoints treat an array or object you send as the complete desired state (for example a product's codes, or an order's lines). Check the resource guide before sending partial data — see the Products Guide and Orders & Order Lines Guide.

FAQ

How do I map my ERP's company code to a Retraced company ID? If you store companies under your own internal codes, filter /companies by internalCompanyCode. The filter parameter is a URL-encoded JSON object:

# filter = {"internalCompanyCode":"123"}
curl "https://publicapi.retraced.com/api/v2/companies?filter=%7B%22internalCompanyCode%22%3A%22123%22%7D" \
  -H "companyapikey: $API_KEY"

Read the Retraced id from each match. Useful filter keys are name, officialName, city, and internalCompanyCode (all substring, case-insensitive matches), plus country (exact ISO 3166-1 alpha-2 code, e.g. "DE"; comma-separate for multiple: "DE,IT").

⚠️ internalCompanyCode matches partially and case-insensitively — searching for "123" also returns "1234" and "ABC123". Confirm the internalCompanyCode on each returned company before trusting the match. Also note that if the filter value isn't valid JSON it is silently ignored (you get an unfiltered list, not an error), so URL-encode it carefully.

What does an order's status mean? Order status (IN_PROGRESS, IN_REVIEW, COMPLETED) is not tied to any Retraced workflow — the platform does not act on it. Assign it whatever meaning fits your process.

How do I know what changed in the API? See the release notes for a history of public API changes.

Related reading

• Products Guide — the Style → Variant → SKU model, codes, filters, inheritance
• Orders & Order Lines Guide — orders, lines, parties, archiving
• Materials Guide and BOM Guide — composition and bills of materials
• DPP / Label Provider Guide and LCA Provider Guide — partner integration walkthroughs
• API Reference — interactive endpoint and schema documentation
• All integration guides