BOM Guide - Headers, Lines & Inheritance

How to read and write Bills of Materials (BOMs) through the Retraced public API, and - more importantly - how BOM inheritance and copy-on-write work. If you only read one section, read The Mental Model. It explains the one behavior that surprises every integrator: modifying an inherited BOM changes its IDs.

Setup

BASE_URL="https://publicapi.retraced.com/api/v2"
API_KEY="your-api-key"        # provided by Retraced; wrap in single quotes if it contains $
STYLE_ID="style-123"          # the product you are working with

Requests are authenticated with the API key header:

curl "$BASE_URL/bom-headers?styleId=$STYLE_ID" \
  -H "companyapikey: $API_KEY"

All responses use the standard envelope:

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

The Mental Model

Data model

A BOM is not stored per product. It is stored once and linked to products:

BOM Header  (name, description)            ── the BOM itself, stored once
   │
   ├── BOM Links   (styleId, isOwner, isMainBom, version, effective dates)
   │                ── one link per product that "has" this BOM
   │
   └── BOM Lines   (component styleId, quantity, weight, placement, ...)
                    ── the components inside the BOM

Products form a 3-level hierarchy - Style → Variant → SKU - and all three levels are addressed by the same kind of ID (the styleId parameter accepts a style, variant, or SKU ID).

Inheritance = shared links

When you create a BOM on a style, the platform automatically links that same header to every variant and SKU underneath it:

Style "Summer T-Shirt"  ──link (isOwner: true)──┐
  ├─ Variant "Red"      ──link (isOwner: false)─┼──►  BOM Header "T-Shirt Assembly"
  │    └─ SKU "Red / M" ──link (isOwner: false)─┤
  └─ Variant "Blue"     ──link (isOwner: false)─┘

• The product that created the BOM owns it (link.isOwner: true).
• Children inherit it (link.isOwner: false) - they see the exact same header and lines. There is no copy; it is literally the same record.
• Because it's the same record, edits made by the owner are instantly visible to every inheriting child.
• Inheritance only flows downward, so a top-level style always owns its BOMs; only variants and SKUs can inherit.

Note: Child links are created asynchronously. After creating a BOM on a style, the variant/SKU links appear within a few seconds - don't expect them synchronously in the create response.

Copy-on-write: what happens when a child edits an inherited BOM

A child cannot edit a BOM it doesn't own - that would silently change its siblings and parent. Instead, the platform performs copy-on-write:

1. The child's link to the shared header is deleted.
2. The header is duplicated - new header ID, name suffixed with " (Copy)" (unless your request supplied a new name), all lines copied with new line IDs. The copied header and lines start with externalId: null - your externalIds stay on the originals (see Your own IDs).
3. The child gets a new link to the copy with isOwner: true and version: 1.
4. The child is now permanently detached: future changes to the parent's BOM no longer reach it. Its own children are not moved over - copy-on-write never creates child links, so a forked variant's SKUs keep their links to the original shared header.

Before                                  After variant "Red" edits a line

Style    ──(owner)───►  Header A       Style    ──(owner)───►  Header A
Variant  ──(inherit)─►  Header A       Variant  ──(owner)───►  Header A (Copy)  ← new IDs
SKU      ──(inherit)─►  Header A       SKU      ──(inherit)─►  Header A         ← stays on original

⚠️ The single most important consequence: after copy-on-write, the BOM header ID and every BOM line ID are different. Never cache BOM IDs across writes - always take the IDs from the response of your last write.

⚠️ Copy fidelity caveat: lines copied during copy-on-write currently do not preserve the component reference (styleId) or the isMainComponent flag - only the line you explicitly created/edited in the same request carries the values you sent. After a fork, re-fetch the copied BOM's lines and re-apply component references where needed.

What triggers copy-on-write - and what doesn't

Operations through the owner (isOwner: true) always modify the shared record directly - every inheriting child sees the change immediately.

Endpoint Reference

Placements (the position a component occupies, e.g. "Front placket") are managed via GET /bom-placements and POST /bom-placements - see the API Reference. Use GET /bom-placements to find the placementId values used on BOM lines.

Your own IDs (externalId)

Product IDs. Every product ID in this guide - styleId, link.styleId, entity.styleId, component.styleId - accepts either the Retraced ID or the externalId you set when creating the product. GET /bom-headers?styleId=DRS-2024-001 and GET /bom-headers?styleId=style_01K... are equivalent. See the Products Guide for the rules.

BOM headers, lines and placements carry an externalId of their own:

• Set it with externalId on POST /bom-headers, POST /bom-lines and POST /bom-placements, or on PUT /bom-headers/:id and PUT /bom-lines/:id. On a PUT, omit it to keep the current value and send null to clear it. A placement's externalId can only be set when the placement is created.
• Up to 255 letters, digits and _ . ~ : @ -, unique within your company per resource. A value already in use is rejected with 409 external_id_already_exists.
• Every BOM ID field then accepts it in place of the Retraced ID: :id on the header, line and placement endpoints, bomHeaderId, placementId, bomHeaderIds[], bomLineIds[], and the ids, bomHeaderId and placementId list filters.
• Every response returns externalId - null when none is set. The id fields in responses are always Retraced IDs.

Copy-on-write never copies an externalId. When a variant or SKU edits a BOM it only inherits, the copy and all its lines start with externalId: null, and the originals keep theirs - the style and its other children still use them. So after a fork:

• the write response carries the copy's new id (for a line write, the new bomHeaderId) with externalId: null;
• your old externalIds still point at the original BOM. Writing through the forked variant with them returns 404 bom_line_link_not_found (lines) or 404 bom_header_not_found (headers), because the variant is no longer linked to the original;
• to tag the copy, send externalId in the same request that forks it. The value must be new - one the original still holds is rejected with 409 and nothing is copied. For the other copied lines, list them with GET /bom-lines?bomHeaderId=<new id> and set an externalId on each with PUT /bom-lines/:id.

# Variant "Red" only inherits PLM-BOM-77, so renaming it through the variant forks a copy.
curl -X PUT "$BASE_URL/bom-headers/PLM-BOM-77" \
  -H "companyapikey: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "styleId": "SAP-STYLE-9-RED", "name": "T-Shirt Assembly (Red)", "isMainBom": true, "externalId": "PLM-BOM-77-RED" }'
# → data.id is the copy's new Retraced ID, data.externalId is "PLM-BOM-77-RED".
#   PLM-BOM-77 still identifies the style's BOM.

Reading BOM Data

Step 1 - list a product's BOM headers

styleId is required and can be a style, variant, or SKU ID.

curl "$BASE_URL/bom-headers?styleId=$STYLE_ID" \
  -H "companyapikey: $API_KEY"

Response (200):

{
  "metadata": {
    "success": true,
    "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
  },
  "data": [
    {
      "id": "bomhdr_01J9XYZ...",
      "name": "T-Shirt Assembly",
      "description": null,
      "forCompanyId": "company-123",
      "version": 1,
      "effectiveStartDate": "2026-06-01T08:00:00.000Z",
      "effectiveEndDate": null,
      "isArchived": false,
      "link": {
        "styleId": "style-123",
        "isMainBom": true,
        "isOwner": true
      },
      "createdAt": "2026-06-01T08:00:00.000Z",
      "updatedAt": "2026-06-01T08:00:00.000Z",
      "createdByUserId": "user-1",
      "createdByCompanyId": "company-123",
      "updatedByUserId": "user-1",
      "updatedByCompanyId": "company-123"
    }
  ]
}

Read link.isOwner to know whether this product owns the BOM or inherits it - that tells you whether your next write will hit the shared record or trigger copy-on-write. version, effectiveStartDate/effectiveEndDate, and isMainBom are also per-link values (see Main BOM & Versioning).

Query parameters:

Boolean filters accept true or false. Pass isMainBom=false / isArchived=false to filter for the false value, or omit the parameter to skip the filter. Any other value (e.g. 1, yes) is rejected with a 400.

Step 2 - list the BOM's lines

BOM_HEADER_ID="bomhdr_01J9XYZ..."

curl "$BASE_URL/bom-lines?bomHeaderId=$BOM_HEADER_ID&include=entity,placement" \
  -H "companyapikey: $API_KEY"

Response (200):

{
  "metadata": {
    "success": true,
    "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
  },
  "data": [
    {
      "id": "bom_line_01J9ABC...",
      "bomHeaderId": "bomhdr_01J9XYZ...",
      "placementId": "plc_01J9...",
      "styleId": "style-button-456",
      "quantity": 4,
      "quantityUnit": "PIECES",
      "weight": 2.5,
      "weightUnit": "GRAM",
      "countryOfOrigin": "PT",
      "isMainComponent": false,
      "createdAt": "2026-06-01T08:05:00.000Z",
      "updatedAt": "2026-06-01T08:05:00.000Z",
      "createdByUserId": "user-1",
      "createdByCompanyId": "company-123",
      "updatedByUserId": "user-1",
      "updatedByCompanyId": "company-123",
      "entity": {
        "id": "style-button-456",
        "forCompanyId": "company-123",
        "name": "4-Hole Button 12mm",
        "codes": [{ "codeId": "ERP_ID", "codeValue": "BTN-12-4H" }],
        "suppliers": ["supplier-9"],
        "mainSupplier": "supplier-9"
      },
      "placement": {
        "id": "plc_01J9...",
        "value": "Front placket",
        "forCompanyId": "company-123"
      }
    }
  ]
}

⚠️ styleId means the component here, not the product. On a BOM line, styleId is the ID of the component product (the button, the fabric panel) that sits inside the BOM. Consequently the styleId query filter on GET /bom-lines filters by component, answering "which BOMs use this component?" - not "what are this product's lines?". To get a product's lines, go through its headers: GET /bom-headers?styleId=... → GET /bom-lines?bomHeaderId=....

Query parameters:

Get a single header

GET /bom-headers/:id returns the same header shape as the list, but resolves only through the owner's link. If the header doesn't exist - or exists but is only inherited by your products - it responds 404 bom_header_not_found. When in doubt, use the list endpoint with styleId, which returns both owned and inherited BOMs.

curl "$BASE_URL/bom-headers/$BOM_HEADER_ID" \
  -H "companyapikey: $API_KEY"

Creating a BOM

Create the header

Attach it to the level where it's shared. Attaching to a style propagates it to all variants and SKUs; attaching to a variant propagates to that variant's SKUs only; attaching to a SKU doesn't propagate anywhere.

curl -X POST "$BASE_URL/bom-headers" \
  -H "companyapikey: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "T-Shirt Assembly",
    "description": "Main production BOM",
    "externalId": "PLM-BOM-77",
    "link": {
      "styleId": "style-123",
      "isMainBom": true
    }
  }'

Response (201) - note this is a flat shape, without the link object the list endpoint returns:

{
  "metadata": { "success": true },
  "data": {
    "id": "bomhdr_01J9XYZ...",
    "name": "T-Shirt Assembly",
    "description": "Main production BOM",
    "externalId": "PLM-BOM-77",
    "forCompanyId": "company-123",
    "isMainBom": true,
    "version": 1,
    "effectiveStartDate": "2026-06-01T08:00:00.000Z",
    "effectiveEndDate": null,
    "isArchived": false,
    "createdAt": "2026-06-01T08:00:00.000Z",
    "updatedAt": "2026-06-01T08:00:00.000Z",
    "createdByUserId": "user-1",
    "createdByCompanyId": "company-123",
    "updatedByUserId": "user-1",
    "updatedByCompanyId": "company-123"
  }
}

The creating product owns the new BOM; to see link.isOwner (and version/effective dates), use GET /bom-headers?styleId=.... Child links (isOwner: false) are created asynchronously in the background.

BOM_HEADER_ID="bomhdr_01J9XYZ..."   # from the response

Add lines

Each line adds one component (which must itself be a product in your catalog, with at least one product code - e.g. an ERP ID):

curl -X POST "$BASE_URL/bom-lines" \
  -H "companyapikey: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bomHeaderId": "'$BOM_HEADER_ID'",
    "entity":    { "styleId": "style-123" },
    "component": { "styleId": "style-button-456" },
    "placementId": "plc_01J9...",
    "quantity": 4,
    "quantityUnit": "PIECES",
    "weight": 2.5,
    "weightUnit": "GRAM",
    "countryOfOrigin": "PT",
    "isMainComponent": false
  }'

Two distinct product references - don't mix them up:

bomHeaderId on its own cannot replace entity.styleId: one header is linked to the style and every variant/SKU inheriting it, each link with its own isOwner. The entity you pass is what decides whether the shared BOM is edited or forked for that product first.

quantity/weight are optional non-negative numbers. quantityUnit/weightUnit must be platform unit enum values (see the OpenAPI reference at https://publicapi.retraced.com/api/docs) and must be among the units of measure configured for the component's style type. Read the accepted units before you write: GET /style-types returns quantityUnits and weightUnits per type, and GET /bom-lines?include=entity returns them on entity.type for every existing line. A unit outside that list is rejected with 400 invalid_bom_quantity_unit / 400 invalid_bom_weight_unit, and the error message lists what is accepted. When the component's style type has no units configured, the platform-wide quantity and weight lists apply.

On PUT /bom-lines/:id, a unit that is already stored on the line is always accepted as long as component.styleId is unchanged — a line written before its style type was configured stays editable without having to change its unit.

Response (201): the created line. If entity.styleId only inherited the BOM, copy-on-write fired and the response's bomHeaderId is a new header - see The Mental Model.

What a BOM line records - and what it doesn't

• Component type vs placement are different axes. A BOM line points at a component product via component.styleId; what kind of component it is (button, zipper, main fabric, …) comes from that product's styleTypeId - resolve it with GET /styles/{component.styleId}. Placement is where the component sits on the garment: set placementId on the line and look the value up via GET /bom-placements. One says what, the other says where - a "Front placket" placement can hold a button, a zipper, or a label.
• One quantity and one weight per line. Each line has a single quantity + quantityUnit and a single weight + weightUnit. To capture two different measurements of the same component - e.g. a fabric's width and its yarn count - add two BOM lines for that component, one per measurement.
• Recycled/synthetic content is not a BOM-line field. There is no isRecycled flag on a BOM line. Whether a material is recycled or synthetic lives on the raw material and is read through material composition (GET /material-lines?...&include=rawMaterials → rawMaterial.isRecycled / rawMaterial.isSynthetic), independently of the BOM. See the Materials Guide.

Modifying a BOM

The same request behaves differently depending on the isOwner flag of the link between the entity you pass and the header - check it first via GET /bom-headers?styleId=....

Update the header

curl -X PUT "$BASE_URL/bom-headers/$BOM_HEADER_ID" \
  -H "companyapikey: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "styleId": "style-123",
    "name": "T-Shirt Assembly v2",
    "description": "Updated",
    "isMainBom": true
  }'

All body fields except description are required. styleId identifies through which product you are editing:

• Owner: header updated in place - all inheriting children see the new name/description.
• Inherited + name/description changed: copy-on-write. The response data.id is the new header ID for this product (named with your supplied name, not "(Copy)").
• Inherited + only isMainBom changed: no copy - isMainBom is a per-link property, so the change applies to this product's link only.

Edit a line

BOM_LINE_ID="bom_line_01J9ABC..."   # from the list or create response

curl -X PUT "$BASE_URL/bom-lines/$BOM_LINE_ID" \
  -H "companyapikey: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity":    { "styleId": "variant-red-789" },
    "component": { "styleId": "style-button-456" },
    "quantity": 6,
    "quantityUnit": "PIECES"
  }'

entity and component are required; component.styleId is the line's component (send the current one back unless you're swapping the component). Here entity.styleId is the variant "Red" from the inheritance diagram - an inherited link, so copy-on-write applies:

• Owner: line updated in place.
• Inherited: the entire BOM is duplicated for entity.styleId, and your edit lands on the copied line. The response contains the new line ID and new bomHeaderId - discard the old ones.
• If nothing actually changed, the call short-circuits and returns the existing line (no duplication).

⚠️ Omitted optional fields are cleared, not kept. The update sets every optional field (placementId, quantity, weight, countryOfOrigin, units, isMainComponent) to the value you send, defaulting to null/false when omitted. Always send the full desired state of the line.

Delete lines

curl -X POST "$BASE_URL/bom-lines/delete" \
  -H "companyapikey: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "styleId": "variant-red-789",
    "bomLineIds": ["bom_line_01J9ABC..."]
  }'

Here styleId is the product whose BOM you are editing (the entity) - unlike the GET /bom-lines filter, where it means the component. Up to 100 IDs per call.

• Owner: lines are hard-deleted from the shared BOM.
• Inherited: copy-on-write - the BOM is duplicated without the deleted lines, and the product is detached from the shared BOM.

Response (200): { "deletedLines": [...], "duplicatedHeaders": [], "orphanedHeaders": [], "errors": [] }

Two things to know about this endpoint:

• It is all-or-nothing: if any requested ID doesn't exist (or isn't linked to styleId), the whole request fails with 404 bom_lines_not_found - nothing is deleted and the errors array is never used.
• After a copy-on-write delete, the response does not contain the new header/line IDs. Re-fetch via GET /bom-headers?styleId=... → GET /bom-lines?bomHeaderId=....

Delete / detach a BOM header

curl -X POST "$BASE_URL/bom-headers/delete" \
  -H "companyapikey: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "styleId": "style-123",
    "bomHeaderIds": ["bomhdr_01J9XYZ..."]
  }'

• Through the owner: the header and all its lines are deleted, and every inherited child link is removed in the same operation (synchronously). The BOM is gone for the whole product family.
• Through an inheriting child: the child detaches from the BOM - its link and its own descendants' links are removed (detaching a variant also detaches that variant's SKUs). The parent and siblings keep the BOM.

Response (200): { "deletedHeaders": [...], "deletedLinks": [...], "errors": [...] } - unlike line deletion, per-ID failures are reported in errors without failing the whole request.

Main BOM & Versioning

isMainBom, version, and effectiveStartDate/effectiveEndDate live on the link, so each product in the hierarchy designates its own main BOM independently - without copy-on-write.

• One main BOM per product. Setting isMainBom: true on one link automatically demotes the product's previous main BOM (the demoted link gets effectiveEndDate = now and a version bump).
• effectiveStartDate is set when a BOM becomes main; effectiveEndDate is stamped when it is automatically demoted. Together they record when this BOM was the active production spec for that product.
• version increments on each isMainBom transition for that link, and resets to 1 for a header created by copy-on-write.
• Changing isMainBom on a style/variant cascades the change to its children's links asynchronously (children that explicitly chose their own main BOM keep their choice).

Error Reference

Header field limits: name ≤ 255 characters, description ≤ 4000, countryOfOrigin ≤ 100.

Gotchas Checklist

1. IDs are not stable across writes. Any write through a product with link.isOwner: false duplicates the header and all lines with new IDs and externalId: null. Always re-read IDs from the write response (or re-fetch, for line deletes), and send externalId in the forking request if you want to tag the copy.
2. Check link.isOwner before writing if you need to predict whether your change affects the whole product family (owner) or forks a private copy (inherited).
3. Copy-on-write detaches permanently. Once a variant forks its BOM, later changes to the style's BOM never reach that variant. There is no re-attach API, and deleting the variant's copy does not restore the inherited link - inherited links are only auto-created when a BOM is first created on a parent, or when a new child product is created. A detached variant that deletes its copy simply ends up with no BOM. Fork deliberately.
4. styleId on a BOM line = the component, not the owning product. GET /bom-lines?styleId=X answers "where is X used as a component?".
5. Boolean query filters accept only true or false (isArchived, isMainBom, isMainComponent) - any other value is rejected with a 400. Omit the parameter to skip the filter.
6. PUT /bom-lines/:id is a full replace of the line's optional fields - omitted fields are nulled.
7. Components must have at least one product code before they can be used in a BOM line.
8. Child links are created asynchronously after POST /bom-headers on a style/variant - allow a few seconds before expecting them on children.
9. Duplicated headers are renamed "<name> (Copy)" (a header update with a new name uses your name instead). Don't rely on BOM names as identifiers.
10. List limit is capped at 100.

Related Reading

• Materials Guide - material composition trees: the same link/inheritance model, but with different copy-on-write behavior
• Products Guide - Style → Variant → SKU lifecycle and field inheritance (null = inherit)
• API Reference - interactive endpoint and schema documentation, including /bom-placements
• All integration guides