Materials Guide — Headers, Lines & Inheritance

How to read and write material compositions through the Retraced public API, and — more importantly — how material inheritance and copy-on-write work. Materials share the BOM's link-based inheritance model but with one extra twist: copy-on-write behaves differently for header updates and line writes. If you only read one section, read The Mental Model.

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/material-headers?styleId=$STYLE_ID" \
  -H "companyapikey: $API_KEY"

All responses use the standard envelope:

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

The Mental Model

Data model

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

Material Header  (name, description)        ── the composition, stored once
   │
   ├── Material Links  (styleId, isOwner, isMainMaterial)
   │                   ── one link per product that "has" this composition
   │
   └── Material Lines  (rawMaterialId, percentage, parentId, countriesOfOrigin, ...)
                       ── a TREE of material entries

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).

Unlike BOM lines (a flat component list), material lines form a tree:

Header "Shell Fabric"
  ├─ Cotton          80%   (parentId: null  → root line, hierarchy 0)
  │    ├─ Organic Cotton    60%   (parentId: <cotton-line-id>, hierarchy 1)
  │    └─ Recycled Cotton   40%
  └─ Polyester       20%   (parentId: null)

Each line carries:

Two tree-wide rules are enforced on every write:

• Percentages: siblings at each level must sum to ≤ 100 (it does not have to equal 100). Exceeding 100 fails with 400 percentage_constraint_violation.
• Countries: a child's countriesOfOrigin must be a subset of its parent's. Violations fail with 400 countries_of_origin_constraint_violation. A parent with no countries cannot have children with countries.

Inheritance = shared links

When you create a material header 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)─┼──►  Header "Shell Fabric"
  │    └─ SKU "Red / M" ──link (isOwner: false)─┤
  └─ Variant "Blue"     ──link (isOwner: false)─┘

• The product that created the header 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.
• Edits made by the owner are instantly visible to every inheriting child.

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

Copy-on-write: TWO different behaviors

For BOMs, every write through an inherited link forks the whole structure. Materials are not that uniform — header updates and line writes behave differently. Both behaviors below are exactly what the API does today; plan your integration around them.

Behavior 1 — line writes (POST /material-lines, PUT /material-lines/:id) through an inherited link: full fork + detach.

1. The header is duplicated — new header ID, name suffixed with " (Copy)" (always, even if you didn't touch the name), all lines copied with new line IDs (parent/child relationships remapped).
2. The product gets a new link to the copy with isOwner: true, and its old inherited link is deleted.
3. Your create/update lands in the copy — the response's materialHeaderId (and line ID, for updates) belong to the new header.
4. The product is now permanently detached: future changes to the parent's composition no longer reach it. Its own children are not moved over — 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

⚠️ Never cache material header or line IDs across writes — always take the IDs from the response of your last write.

Behavior 2 — header updates (PUT /material-headers/:id) through an inherited link: header-only duplicate, NO detach.

Unlike line writes, this duplicates only the header record — the lines are not copied — and the old inherited link is not removed. The product ends up linked to two headers: the original shared one (with its lines) and a new, empty owned copy:

Before                                    After variant PUTs the inherited header

Style    ──(owner)───►  Header A          Style    ──(owner)───►  Header A (lines intact)
Variant  ──(inherit)─►  Header A          Variant  ──(inherit)─►  Header A            ← still there
                                          Variant  ──(owner)───►  Header A (Copy)     ← NEW, ZERO lines

⚠️ Any field triggers this — including an isMainMaterial-only change. There is no change detection on this path, so even re-sending the current values through an inherited link creates another empty copy. The "(Copy)" suffix is applied when your submitted name equals the current name; if you send a new name, your name is used. Practical rule: never PUT /material-headers/:id through a product with link.isOwner: false. If a child product needs its own composition, fork it with a line write (Behavior 1), or create a fresh header on the child.

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

Reading Material Data

Step 1 — list a product's material headers

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

⚠️ styleId is the Retraced internal product ID — not one of your codes[] values. It is the id field returned by the styles endpoint (e.g. style_01KMZ…, variant_…, sku_…), not your ERP number or EAN. Material responses don't echo codes[], so if you only have your own code, resolve it to the Retraced id first via GET /styles?nameOrCode=<your-code> (or ?codeId=…&codeValue=…), then pass that id here.

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

Response (200):

{
  "metadata": {
    "success": true,
    "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
  },
  "data": [
    {
      "id": "mtrialhdr_01KTS...",
      "name": "Shell Fabric",
      "forCompanyId": "company-123",
      "description": null,
      "link": {
        "styleId": "style-123",
        "isMainMaterial": true,
        "isOwner": true
      },
      "createdAt": "2026-06-10T08:00:00.000Z",
      "createdByUserId": "user-1",
      "createdByCompanyId": "company-123",
      "updatedAt": "2026-06-10T08:00:00.000Z",
      "updatedByUserId": "user-1",
      "updatedByCompanyId": "company-123"
    }
  ]
}

Read link.isOwner to know whether this product owns the composition or inherits it — that tells you whether your next write will hit the shared record or trigger copy-on-write. isMainMaterial is also a per-link value (see Main Material).

Query parameters:

Boolean filters accept true or false. Pass isMainMaterial=false / isOwner=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 composition's lines

MATERIAL_HEADER_ID="mtrialhdr_01KTS..."

curl "$BASE_URL/material-lines?materialHeaderId=$MATERIAL_HEADER_ID&include=rawMaterials,countriesOfOrigin" \
  -H "companyapikey: $API_KEY"

Response (200):

{
  "metadata": {
    "success": true,
    "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
  },
  "data": [
    {
      "id": "mtrialln_01KTS...",
      "materialHeaderId": "mtrialhdr_01KTS...",
      "rawMaterialId": "COTTON_BALE",
      "percentage": 80,
      "weights": 120,
      "weightUnit": "GSM",
      "parentId": null,
      "hierarchy": 0,
      "position": 100,
      "countriesOfOrigin": ["PT", "TR"],
      "createdAt": "2026-06-10T08:05:00.000Z",
      "createdByUserId": "user-1",
      "createdByCompanyId": "company-123",
      "updatedAt": "2026-06-10T08:05:00.000Z",
      "updatedByUserId": "user-1",
      "updatedByCompanyId": "company-123",
      "rawMaterial": {
        "id": "COTTON_BALE",
        "name": "Cotton bale",
        "description": "After cotton is harvested, ...",
        "category": "NATURAL_MATERIAL",
        "isRecycled": false,
        "isSynthetic": false
      },
      "countries": [
        {
          "countryCode": "PT",
          "countryName": "Portugal",
          "countryNameLocale": "Portugal",
          "region": "Europe",
          "currencyCode": "EUR",
          "currencyName": "Euro"
        }
      ]
    }
  ]
}

Rebuild the tree client-side from parentId (root lines have parentId: null); order siblings by position.

Query parameters:

Get a single header

GET /material-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 material_header_not_found. When in doubt, use the list endpoint with styleId, which returns both owned and inherited compositions.

curl "$BASE_URL/material-headers/$MATERIAL_HEADER_ID" \
  -H "companyapikey: $API_KEY"

Creating a Composition

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/material-headers" \
  -H "companyapikey: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shell Fabric",
    "description": "Main body composition",
    "link": {
      "styleId": "style-123",
      "isMainMaterial": true
    }
  }'

Response (201): the header with its (owner) link echoed back:

{
  "metadata": { "success": true },
  "data": {
    "id": "mtrialhdr_01KTS...",
    "name": "Shell Fabric",
    "forCompanyId": "company-123",
    "description": "Main body composition",
    "link": { "styleId": "style-123", "isMainMaterial": true },
    "createdAt": "2026-06-10T08:00:00.000Z",
    "createdByUserId": "user-1",
    "createdByCompanyId": "company-123",
    "updatedAt": "2026-06-10T08:00:00.000Z",
    "updatedByUserId": "user-1",
    "updatedByCompanyId": "company-123"
  }
}

The creating product owns the new header. Child links (isOwner: false) are created asynchronously in the background.

MATERIAL_HEADER_ID="mtrialhdr_01KTS..."   # from the response

Add lines — roots first, then children

Create the root lines (parentId: null), then create children using the IDs from the responses:

# Root: Cotton 80%, from Portugal and Turkey
curl -X POST "$BASE_URL/material-lines" \
  -H "companyapikey: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "styleId": "style-123",
    "materialHeaderId": "'$MATERIAL_HEADER_ID'",
    "parentId": null,
    "rawMaterialId": "COTTON_BALE",
    "percentage": 80,
    "weights": 120,
    "weightUnit": "GSM",
    "countriesOfOrigin": ["PT", "TR"]
  }'

Response (201):

{
  "metadata": { "success": true },
  "data": {
    "id": "mtrialln_01KTS...",
    "materialHeaderId": "mtrialhdr_01KTS...",
    "rawMaterialId": "COTTON_BALE",
    "percentage": 80,
    "weights": 120,
    "weightUnit": "GSM",
    "parentId": null,
    "hierarchy": 0,
    "position": 100,
    "countriesOfOrigin": ["PT", "TR"],
    "createdAt": "2026-06-10T08:05:00.000Z",
    "createdByUserId": "user-1",
    "createdByCompanyId": "company-123",
    "updatedAt": "2026-06-10T08:05:00.000Z",
    "updatedByUserId": "user-1",
    "updatedByCompanyId": "company-123"
  }
}

ROOT_LINE_ID="mtrialln_01KTS..."   # from the response

# Child: Organic Cotton, 60% of the Cotton share, Portugal only (subset of parent!)
curl -X POST "$BASE_URL/material-lines" \
  -H "companyapikey: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "styleId": "style-123",
    "materialHeaderId": "'$MATERIAL_HEADER_ID'",
    "parentId": "'$ROOT_LINE_ID'",
    "rawMaterialId": "ORGANIC_COTTON",
    "percentage": 60,
    "countriesOfOrigin": ["PT"]
  }'

Field notes:

• styleId is the product through which you are writing (must be linked to materialHeaderId). Its isOwner flag decides whether copy-on-write fires — if it only inherits the composition, the response's materialHeaderId is a new header (see The Mental Model).
• parentId is required in the body — pass null explicitly for a root line.
• percentage is relative to siblings, so the 60% above means 60% of the Cotton portion. Sibling sums at each level must stay ≤ 100:

{
  "metadata": { "success": false },
  "statusCode": 400,
  "code": "percentage_constraint_violation",
  "message": "Total percentage for material header would exceed 100%. Current total: 80%, Adding: 30%, Total would be: 110%"
}

• A child's countries must be a subset of its parent's:

{
  "metadata": { "success": false },
  "statusCode": 400,
  "code": "countries_of_origin_constraint_violation",
  "message": "Countries of origin [US] are not present in parent material line. Parent countries: [PT, TR]"
}

• rawMaterialId must come from the Retraced materials catalog. There is no public catalog list endpoint — discover IDs via include=rawMaterials on lines you can already see (in your account or another product), or ask your Retraced contact for the catalog. Note the ID is not validated at create time; a typo simply produces a line whose rawMaterial resolves to nothing.

Modifying a Composition

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

Update the header

curl -X PUT "$BASE_URL/material-headers/$MATERIAL_HEADER_ID" \
  -H "companyapikey: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shell Fabric v2",
    "description": "Updated",
    "link": {
      "styleId": "style-123",
      "isMainMaterial": true
    }
  }'

• Owner: header updated in place — all inheriting children see the new name/description. Setting isMainMaterial: true demotes the product's previous main material.
• Inherited: Behavior 2 — a new empty header copy is created for this product and the inherited link stays. Avoid this path (see The Mental Model).

Edit a line

LINE_ID="mtrialln_01KTS..."

curl -X PUT "$BASE_URL/material-lines/$LINE_ID" \
  -H "companyapikey: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "styleId": "style-123",
    "materialHeaderId": "'$MATERIAL_HEADER_ID'",
    "parentId": "'$ROOT_LINE_ID'",
    "rawMaterialId": "ORGANIC_COTTON",
    "percentage": 65,
    "countriesOfOrigin": ["PT"]
  }'

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

⚠️ PUT /material-lines/:id is a full replace — omitted fields are cleared, and omitting parentId MOVES the line. Omitted weights, weightUnit, and countriesOfOrigin are set to null. Omitting parentId doesn't keep the current parent — it re-roots the line to the top level (where it must then satisfy the root-level percentage sum). Always send the line's full desired state, including its current parentId. (position and hierarchy are the exception: they are preserved when omitted — which also means a re-rooted line keeps its old, now-misleading hierarchy value.)

• Changing a root line's countriesOfOrigin is validated against its children: removing a country that a child still uses fails with 400 parent_countries_constraint_violation. This guard applies to root lines only — when restructuring mid-tree, update children before narrowing their parents' countries.

Delete lines

curl -X POST "$BASE_URL/material-lines/delete" \
  -H "companyapikey: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "styleId": "style-123",
    "materialLineIds": ["mtrialln_01KTS..."]
  }'

Up to 100 IDs per call. styleId is the product through which you are deleting.

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

• Owner: lines and their direct children are hard-deleted from the shared composition.
• Inherited: ⚠️ this endpoint does not follow the fork-and-detach pattern you'd expect. What actually happens: a forked copy of the composition (minus the deleted lines) is created and linked to your product with isOwner: true — but the requested lines are also deleted from the original shared header, affecting the owner and all other inheriting products, and your old inherited link is not removed (the product stays linked to both headers). Do not delete lines through a product with link.isOwner: false unless you intend to modify the shared composition for everyone.

Three more things to know about this endpoint:

• duplicatedHeaders and orphanedHeaders are always empty, even when a fork was created. To find a forked header, re-fetch GET /material-headers?styleId=....
• Invalid IDs are reported per-item in errors ({ materialLineId, message }) without failing the whole request — valid IDs in the same call are still deleted.
• The cascade is one level deep. Deleting a line removes the line and its direct children, but grandchildren are left in place with a dangling parentId. On trees deeper than two levels, delete bottom-up (deepest lines first).

Delete / detach a composition header

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

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

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

Main Material

isMainMaterial lives on the link, so each product in the hierarchy designates its own main material independently.

• One main material per product. Setting isMainMaterial: true (on create, or on a PUT through the owner link) automatically demotes the product's previous main material.
• Changing it on a style/variant propagates to its children's links asynchronously.
• ⚠️ Do not toggle it through an inherited link. isMainMaterial is per-link, but PUT /material-headers/:id through an inherited link still triggers the header-only duplicate (Behavior 2) — and the automatic demotion of the previous main does not run on that path. Toggle it through the owner, or set it when creating the child's own composition.

Error Reference

Field limits: name ≤ 255 characters, description ≤ 4000, weightUnit ≤ 255, percentage 0–100, weights ≥ 0, country codes exactly 2 characters, materialLineIds ≤ 100 per delete call.

Gotchas Checklist

1. IDs are not stable across line writes through inherited links. The fork renames the header to "<name> (Copy)" and re-IDs the header and every line. Always re-read IDs from the write response.
2. Check link.isOwner before writing — it decides whether your change hits the whole product family (owner) or behaves per the trigger table (inherited).
3. Never PUT /material-headers/:id through an inherited link — any field, even isMainMaterial alone, creates an extra empty header copy without detaching.
4. Never POST /material-lines/delete through an inherited link — it deletes the lines from the shared composition (visible to the owner and all siblings) while also creating a fork you'll discover only by re-fetching. Detach with POST /material-headers/delete or fork first with a line edit.
5. PUT /material-lines/:id is a full replace. Omitted optional fields are nulled, and an omitted parentId re-roots the line. Always resend the complete line.
6. Copy-on-write (line writes) detaches permanently. There is no re-attach API; deleting the fork does not restore the inherited link. Fork deliberately.
7. Percentages are per-level and must sum to ≤ 100, not exactly 100. The API never checks completeness — your integration should, if you need full compositions.
8. Child countries ⊆ parent countries, and a parent without countries cannot have children with countries. Build trees top-down with the widest country set at the root.
9. rawMaterialId is not validated — a typo creates a line pointing at nothing. Verify with include=rawMaterials after writing.
10. Line deletion cascades one level only — delete bottom-up on deep trees, or grandchildren are left with dangling parentIds.
11. Child links are created asynchronously after POST /material-headers on a style/variant — allow a few seconds before expecting them on children.
12. Boolean query filters accept only true or false (isMainMaterial, isOwner) — any other value is rejected with a 400. Omit the parameter to skip the filter.
13. List limit is capped at 100.

Related Reading

• BOM Guide — Bills of Materials: the same link/inheritance model with uniform copy-on-write
• Products Guide — Style → Variant → SKU lifecycle and field inheritance (null = inherit)
• API Reference — interactive endpoint and schema documentation
• All integration guides