How do I safely update a product via the External API without affecting its BOMs or other associations?
Last updated: August 20, 2026
Partial product updates via the External V1 API
The External V1 API product endpoints (PUT /products/{id} and POST /products in create-or-update mode) support partial updates: you only need to send the fields you want to change. Fields omitted from the request body are left untouched.
How BOM associations are handled
BOM associations on a product are only modified when you explicitly include a boms key in your request body.
Omit
boms→ existing BOM associations are preserved exactly as they are.Send
boms: []→ all BOM associations are removed.Send
boms: [1, 2, 3]→ BOM associations are synced to exactly those BOM IDs (replacing whatever was there before).
This means a request like the following is completely safe — it changes only the product name and leaves BOMs (and all other unmentioned fields) untouched:
PUT /products/42
{
"name": "Updated Product Name"
}
Common mistake that caused BOM loss (now fixed)
Before this fix shipped (August 2026), the API silently detached all BOMs whenever boms was absent from a partial update payload. If you noticed BOM associations missing from products that were updated via the API around or before that date, re-attaching them via the boms field in a subsequent update will restore them.
Re-attaching BOMs via the API
To add or restore BOMs on a product without disturbing anything else:
PUT /products/42
{
"boms": [5, 12]
}
This syncs the product's BOM associations to BOM IDs 5 and 12. All other product fields remain unchanged.
Tips for safe API product updates
Goal | What to send |
|---|---|
Change only name/price/tags | Omit |
Add a BOM without changing others | Send full desired BOM ID list (the field is a full sync, not append-only) |
Remove all BOMs intentionally | Send |
Leave BOMs as-is | Omit the |
The same safe-omit behavior applies to tags, kit_items, custom_fields, and variants — fields are only written when present in the request body.