Public API — Release Notes

Changes to the Retraced Public API: new endpoints and fields, behavior changes, fixes, and deprecations. Platform releases that do not affect the public API are not listed here.

See also the API Reference and the integration guides.

v2.1204.0 — 2026-10-22

• AddedOne guide for your own IDs and codes - External IDs & Mapping

  A new guide, External IDs & Mapping, explains in one place how to use your own identifiers with the API: externalId on products, BOM, materials, orders and order lines; the Internal Company Code for the companies in your network; and Constant Mappings for your product-type, material and facility-process codes. It covers calling endpoints by externalId instead of the Retraced ID, how externalId relates to an order's orderNumber, where to manage each kind of code (in the Retraced dashboard under Company settings → API → Constants Mapping, or with /api/v2/constant-mappings), and request/response examples for each resource. Every resource group in the API Reference now links to it.

  Three behaviours changed with it:

  • POST and PUT /api/v2/material-lines now reject a rawMaterialId that is neither a Retraced material ID nor one of your mapped material codes with 404 material_not_found. Previously the value was saved as sent.
  • POST /api/v2/bom-placements now answers an invalid body with 400, as documented, instead of 500.
  • An Internal Company Code resolves against the value shown on your Network page. A code of a company you have unlinked from your network no longer resolves.

v2.1203.0 — 2026-10-22

• AddedManage your own product-type, material and facility-process codes with the Constant Mappings endpoints

  You can now manage the codes you use in place of Retraced ids from the API, with your API key, instead of in the dashboard only. Four new endpoints under /api/v2/constant-mappings list, create, change and delete your product-type, material and facility-process codes.

  • GET /api/v2/constant-mappings lists your mappings, paginated. Filter by resourceType, retracedId or externalId (exact match) and sort by externalId, retracedId, resourceType or updatedAt.
  • POST /api/v2/constant-mappings creates up to 100 mappings in one call, of any mix of resource types. Each item names the resourceType (STYLE_TYPE, RAW_MATERIAL or FACILITY_PROCESS), the Retraced id (retracedId) and your code (externalId), plus an optional externalName.
  • PATCH /api/v2/constant-mappings changes the code and/or the name of up to 100 mappings by id. The Retraced id a mapping points to cannot be changed; delete the mapping and create another.
  • DELETE /api/v2/constant-mappings?ids=a,b,c deletes up to 100 mappings by id. Or name them by your own codes instead: DELETE /api/v2/constant-mappings?resourceType=RAW_MATERIAL&externalIds=ERP-MAT-COT,ERP-MAT-WOOL (one resource type per call).

  Every write succeeds or fails as a whole: an unknown Retraced id (404), a code you have already mapped for the same resource type (409), a code given twice in one call (400) or an id that is not one of your mappings (404) rejects the whole call, nothing is written, and the error message names…

v2.1201.0 — 2026-10-21

• AddedSupport external mapping for facility processes

  You can now send your own facility-process codes instead of Retraced facility process IDs on orders:

  • buyerFacilityProcess, supplierFacilityProcess and receiverFacilityProcess on POST /api/v2/orders and PATCH /api/v2/orders/{id} accept a facility-process code you mapped in Retraced under Settings → Mappings → Facility processes. The match is exact and case-sensitive.
  • Several of your codes can point to the same Retraced facility process; each code maps to exactly one.

  Rules, the same as for company, product-type and material codes:

  • A Retraced ID always wins: a value that is a valid facility process ID is used as is. For that reason a code equal to an existing facility process ID cannot be mapped.
  • An unknown value is passed through unchanged, so the error is the same as before (400, code invalid_facility_process_ids).
  • Responses keep returning Retraced IDs. The valid IDs are listed by GET /api/v2/facility-processes.

  See /api/v2/guides/getting-started and /api/v2/guides/order-hub for examples.

v2.1199.0 — 2026-10-21

• AddedAccept your own company, style-type and material codes in place of [secure] IDs

  You can now send your own codes instead of Retraced IDs in three places:

  • Company fields (buyerCompanyId, supplierCompanyId, receiverCompanyId, vendorCompanyId, factory, forCompanyId, suppliers, mainSupplier, vendors, the companyId/companyIds/excludeCompanyIds filters, GET /api/v2/companies/{id} and /esg) accept the internal company code you assigned to that company in Retraced. The match is exact and case-sensitive. A code you gave to several companies is not resolved.
  • styleTypeId on POST/PUT /api/v2/styles and the GET /api/v2/styles filter accepts your own product-type code mapped in Retraced.
  • rawMaterialId on POST/PUT /api/v2/material-lines and the GET /api/v2/material-lines filter accepts your own material code mapped in Retraced.

  Rules that apply everywhere:

  • A Retraced ID always wins: if a value is a valid Retraced ID it is used as is, even when you also mapped the same string as a code.
  • An unknown value is passed through unchanged, so the error you get is the same as before (404 or 400).
  • Responses keep returning Retraced IDs. To find the Retraced ID behind one of your company codes, use GET /api/v2/companies?filter={"internalCompanyCode":"<code>"}.
  • Product-type and material codes are set up by your Retraced contact. Each code maps to exactly one Retraced ID.

  See /api/v2/guides/getting-started for examples.

v2.1187.0 — 2026-10-15

• AddedAdd optIn includeAllFacilityProcesses querystring to show all facility process for a supply chain grouped by production process

  GET /api/v2/supply-chains/{id} has a new optional query parameter: includeAllFacilityProcesses.

  Some facilities in a supply chain map work across several production stages. For example, one facility might do spinning (yarn processing, T3), knitting (fabric processing, T2) and laundry (manufacturing, T1). By default nothing changes: the facility is listed once, under the stage of its featured process, and facilityProcesses lists all its processes.

  With ?includeAllFacilityProcesses=true, the facility is listed under each stage it works in:

  • Each entry has that stage's tier and productionProcess, and only that stage's processes in facilityProcesses.
  • All entries share the same node id. De-duplicate by id if you build a list of facilities.
  • links are unchanged and refer to the shared id.

  The parameter accepts true or false (default false). Any other value is rejected with 400. Supply chains from product mapping and order tracing are not affected.

v2.1183.0 — 2026-10-14

• AddedAdd external id support for style properties

  You can now give style properties your own externalId, and use it wherever products reference a style property. Format, responses and updates follow the same rules as for BOMs and material compositions.

  Style properties (brands, departments, seasons, collections, custom properties)

  • Create only: POST /api/v2/style-properties accepts externalId. It can only be set when the property is created, and must be unique across all your style properties, whatever their category.
  • Lookup: GET /api/v2/style-properties?externalId=... finds a property by your ID.
  • Use on products: brands, departments, seasons, collections and customProperties on POST and PUT /api/v2/styles accept a property's externalId in place of its ID. Products still store and return Retraced IDs in these fields. A value that matches no property of that category is still rejected with 404.
  • Shown on reads: include=styleProperties now shows each property's externalId next to its id.
  • New list filter: GET /api/v2/styles?propertyExternalIds=... takes a comma-separated list of property externalIds.
    • Each value filters by the brand, department, season or collection it belongs to.
    • Values that match no property are ignored. If none match, the result is empty.
    • Custom properties can't be used as a filter and return 400 unsupported_property_filter.

v2.1182.0 — 2026-10-14

• AddedAdd external id support for style material headers and lines

  You can now give material composition headers and lines your own externalId. Format, uniqueness, responses and updates follow the same rules as for BOMs.

  Material compositions

  • Headers: POST /api/v2/material-headers and its update accept externalId. Any material composition ID accepts it, including materialHeaderId on material lines.
  • Lines: POST /api/v2/material-lines and PUT /api/v2/material-lines/{id} accept externalId. PUT /api/v2/material-lines/{id}, POST /api/v2/material-lines/delete and every parentId accept it as the line ID.

  Inherited BOMs and compositions

  • Edits create a copy: editing a BOM or composition that a variant or SKU only inherits creates a private copy for that product.
  • The copy starts empty: it has externalId: null unless you send one in the same request, and the response carries the copy's new ID.
  • The original keeps its value: a value the original still holds is rejected with 409.

v2.1181.0 — 2026-10-14

• AddedAdd external id for bom header lines placement public api

  You can now give BOM headers, lines and placements your own externalId, the same way products already work. Use your own ID in place of the Retraced ID, with no lookup first.

  Common rules

  • Format: up to 255 letters.
  • Uniqueness: unique within your company for each resource type. A value already in use is rejected with 409 external_id_already_exists, and the error names the record that holds it.
  • Responses: every response returns externalId, or null when none is set.
  • Updates: where an update endpoint exists, omit externalId to keep the current value or send null to clear it.

  BOMs

  • Headers: POST /api/v2/bom-headers and its update accept externalId. Any BOM header ID accepts it in place of the Retraced ID, including bomHeaderId on BOM lines and the ids filter on the list.
  • Lines: POST /api/v2/bom-lines and PUT /api/v2/bom-lines/{id} accept externalId. PUT /api/v2/bom-lines/{id} and POST /api/v2/bom-lines/delete accept it as the line ID.
  • Placements: POST /api/v2/bom-placements accepts externalId. placementId on BOM lines, GET /api/v2/bom-placements/{id} and the ids filter on the list accept it as the placement ID.

v2.1178.0 — 2026-10-13

• AddedSupport external id on orders and order lines endpoints

  Orders and order lines now support your own identifier, externalId. Set it when you create or update an order (POST /api/v2/orders, PATCH /api/v2/orders/{id}), on the order and on each line. If you leave it out on PATCH, the current value is kept; send null to clear it. It is returned on every order and order line, and is null when not set.

  You can use an externalId anywhere an order or order-line ID is expected: {id} on GET, PATCH and DELETE /api/v2/orders/{id}, lines[].id on PATCH, {lineId} on GET /api/v2/order-lines/{lineId}, and orderId on GET /api/v2/order-lines. If a value matches both a Retraced ID and an externalId, the Retraced ID wins.

  An externalId must be unique within your company; a duplicate returns 409 (external_id_already_exists). It can be up to 255 characters of letters, digits and _ . ~ : @ -

v2.1177.0 — 2026-10-13

• AddedSupply chain nodes now list every facility process performed at the facility

  facilityProcesses on each supply chain node now lists every facility process recorded for that node instead of only its featured one. The field is still an array of display names, and its first entry is unchanged: the featured process that decides the node's productionProcess and tier. The entries after it may belong to a different production process than the node's own. Nothing changes for nodes that record a single process.

v2.1168.0 — 2026-10-07

• AddedFindings on a public audit are visible to companies connected to the audited company

  GET /api/v2/capa/findings?scope=network and GET /api/v2/capa/findings/{id} now also return findings raised on a public audit of a company you are connected to, not only findings on audits explicitly shared with you. If you archived your share of such an audit, its findings stay hidden. Plans and actions are unchanged. See Who can see what in the CAPA guide.

v2.1166.0 — 2026-10-07

• AddedCustom properties become company-defined labels on styles, variants and SKUs

  Products now carry a customProperties list: labels your company defines for itself, with no fixed meaning in Retraced (a capsule, an internal range, a sourcing programme).

  • Create a label with POST /api/v2/style-properties and "category": "customProperties". Values are unique per company; a duplicate returns 409.
  • List your labels with GET /api/v2/style-properties?category=customProperties.
  • Attach labels on POST /api/v2/styles and PUT /api/v2/styles/{id} as an array of label IDs. A single ID string is also accepted. An unknown ID returns 404.
  • Responses always return customProperties as an array of IDs. Add include=styleProperties to get the resolved labels.
  • Variants and SKUs inherit the style's labels until they set their own, like brands and seasons.

  Before this change the field accepted arbitrary text and was not validated or inherited. See the Products Guide.

v2.1160.1 — 2026-10-05

• FixedShow formatting in release notes and the weekly email

  Descriptions on the release notes page and in the weekly email now show their formatting: inline code, bold text, lists and links. Before, they appeared as raw markdown, for example **beta** instead of beta.

  The weekly email also has a new layout. It opens with the number of changes since your last email, lists each change with its version and release date, keeps breaking changes at the top under "Action required", and ends with a button to all release notes.

  No action is needed.

v2.1158.0 — 2026-10-02

• AddedOrder Hub orders and order lines are marked as beta

  The Order Hub endpoints (/api/v2/orders, /api/v2/order-lines) are now marked as beta in the API Reference and guides. They are ready to use today, but request and response shapes may still change; every change is announced in the release notes.

v2.1157.0 — 2026-10-01

• AddedAdd "Rolls" as a supported quantity unit

  ROLL is now an accepted unit of measure for order lines. You can send "unit": "ROLL" when creating or updating orders on /api/v2/orders (and on the legacy v0/v1 order and product endpoints), and it may appear in the unit field of order lines you read. No action is needed unless your integration validates unit against a fixed list; if so, add ROLL.

v2.1155.0 — 2026-10-01

• ChangedDeprecate public api v0 and v1

  Public API v0 and v1 are deprecated. They keep working, but every v0/v1 response now carries a Deprecation: @1777593600 header (RFC 9745), and their API Reference pages show a deprecation notice with every endpoint marked as deprecated. Please move new and existing integrations to v2: see the Getting Started guide. No sunset date has been set yet; it will be announced separately.

v2.1153.0 — 2026-10-01

• AddedAdd newsletter feature for public api

  You can now subscribe to email updates about Public API changes on the release notes page (/api/v2/release-notes). Enter your email address and confirm it from the email we send you.

  You get at most one email per week, and only in weeks with Public API changes. Breaking changes are listed first. Every email has a link to unsubscribe.

  Entries on the release notes page and in the email can now include a short description of what changed and what you need to do, if anything.

v2.1152.0 — 2026-09-30

• AddedHonour include on GET /styles/{id}

v2.1141.0 — 2026-09-24

• AddedExpose product information on supply chain node

v2.1099.0 — 2026-09-14

• AddedAdd the audits integration guide

v2.1098.0 — 2026-09-14

• AddedAdd audit endpoints

v2.1096.0 — 2026-09-14

• AddedPublish who created and last changed each CAPA record

v2.1094.1 — 2026-09-14

• ChangedStrengthen the automated checks behind endpoint access rules

v2.1090.0 — 2026-09-13

• AddedAdd the CAPA integration guide

v2.1087.0 — 2026-09-12

• AddedAdd audit finding endpoints
• AddedAdd corrective action plan endpoints

v2.1086.0 — 2026-09-12

• AddedAdd corrective and preventive action endpoints

v2.1085.0 — 2026-09-11

• AddedAdd impact areas and audit types reference-data endpoints

v2.1075.0 — 2026-09-09

• FixedCertificate list fileUrl is a signed download URL, matching get-by-id

v2.1044.0 — 2026-08-28

• ChangedSimplify environment guidance in Getting Started

v2.1027.0 — 2026-08-25

• AddedAttachment template now can be pre-selected on order level (order hub)

v2.986.5 — 2026-08-07

• FixedBOM validation now accepts dynamic units defined from style-type
• FixedMutation and single-resource endpoints no longer document a pagination block

v2.986.0 — 2026-08-06

• AddedFetching a single order line now embeds its parent order
• FixedAttachment templates now paginate like every other list endpoint
• FixedThe receiver company and its facility process must always be sent together on orders
• ChangedImprove integration guides and examples

v2.982.0 — 2026-08-05

• FixedGet supplychain to return supply chain info no check style product story active flag

v2.976.0 — 2026-08-04

• AddedAllow using your own id instead of retraced generated id

v2.974.0 — 2026-08-03

• AddedAdd rate limit all public api

v2.965.0 — 2026-07-30

• FixedSecondary unit is always derived from secondary quantity on order lines

v2.961.0 — 2026-07-29

• AddedAdd handoverDate and deprecate expectedDeliveryDate
• FixedStable ordering and pagination for orders and order lines

v2.957.0 — 2026-07-28

• AddedStandardise every list endpoint on a page size of 20 with a maximum of 100
• FixedOrder writes now reject unknown facility process IDs

v2.955.0 — 2026-07-27

• AddedAdd facility process and production process reference endpoints
• AddedImprove navbar document pages

v2.954.0 — 2026-07-27

• AddedAdd field and parameter descriptions across the API reference

v2.953.0 — 2026-07-27

• AddedAdd a Getting Started guide and expand the integration guides

v2.947.0 — 2026-07-23

• AddedArchived products can no longer be used when creating an order
• AddedCompanies referenced on an order no longer need to be in your network
• AddedCreating an order now requires the caller to be the order's buyer or supplier
• AddedDeleting an order now also removes its linked order-tracing data
• AddedOrder responses now include receiverCompanyId and orderType
• AddedOrders now support multiple responsible users via internalResponsiblePersons
• AddedSetting a receiver on create now requires both receiverCompanyId and receiverFacilityProcess
• AddedThe receiver now defaults to the buyer when omitted on order creation

v2.930.2 — 2026-07-14

• FixedUpdate response example and schema for supply chain tier
• ChangedAdd release note and start gathering information for public api