Merge products (Same product)
POST /rest/v1/products/merge
Makes several products one: the survivor keeps its id, the others are absorbed: their listings move to the survivor and they are archived with merged_into. From then on one stock per variant is shared by all the channels. Nothing changes on the channels except quantity: moved listings keep their own title/description. Per field (title, description, SKU, barcode, price, quantity, photos, tags, category), choices says which product the value comes from (default: the survivor); quantity can also be set per variant. Refused (422) when two products are live on the same channel account (same_channel_account) or their variants do not correspond by SKU or option values (variants_differ). Send dry_run: true first to see the result. Products that don't look like the same item (no SKU or barcode in common, different titles) are listed in looks_different; merging them answers 409 confirm_different unless confirm_different: true is sent. Unknown or archived products answer 404 product_not_found, with them in error.details.product_ids. Prices in merge_preview are 2-decimal strings. Undoable for 30 days (POST /actions/{id}/undo); sales of absorbed products count for the survivor in /sales/products. Events: product.updated for the survivor (data.merged: the absorbed ids) and product.deleted for each absorbed product (data.merged_into).
Required scope: products:write.
Authorization
apiKey Authorization: Bearer nbl_live_... (or nbl_test_... for test mode). Test-mode writes are validated and simulated but never persisted and never touch channels; simulated results are marked simulated.
In: header
Header Parameters
Unique client-generated key (max 255 chars), stored 24h.
length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/products/merge" \ -H "Content-Type: application/json" \ -d '{ "product_ids": [ "string", "string" ] }'{ "object": "merge_preview", "survivor_id": "string", "absorbed_ids": [ "string" ], "looks_different": [ "string" ], "title": "string", "description_excerpt": "string", "variants": [ { "variant_id": "string", "sku": "string", "barcode": "string", "price": "string", "quantity": 0 } ], "listings": [ { "channel": "string", "status": "string", "title": "string", "moved": true } ], "product": { "id": "prod_66a1f09b2", "object": "product", "title": "Vintage denim jacket", "description": "string", "brand": "string", "category": "string", "short_description": "string", "vat_rate": 0, "mpn": "string", "weight": { "value": "string", "unit": "oz" }, "dimensions": { "length": "string", "width": "string", "height": "string", "unit": "in" }, "tags": [ "string" ], "currency": "string", "status": "ready", "requires_attention": { "reason": "string", "message": "string", "channel": "string", "conflicting_product_ids": [ "string" ], "detected_at": "2019-08-24T14:15:22Z" }, "merged_into": "string", "sync_status": "ok", "images": [ { "id": "img_ph1x8", "object": "image", "url": "http://example.com", "alt": "string", "position": 0 } ], "variants": [ { "id": "var_66a1f1", "object": "variant", "sku": "VDJ-M-001", "title": "string", "price": "19.90", "msrp": "24.90", "quantity": 0, "barcode": "string", "grams": 0, "asin": "string", "images": [ { "image_id": "img_66a1f2", "url": "http://example.com", "position": 0 } ], "options": { "property1": "string", "property2": "string" } } ], "listings": [ { "id": "list_9ac2e", "channel_account_id": "string", "channel": "string", "status": "listed", "url_on_channel": "http://example.com", "overrides": { "title": "string", "description": "string" } } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" }}Last updated on October 18, 2026
Need help?
Email us and a human replies, usually within one business day.