curl --request POST \
--url https://omnicommerce.ai/api/v1/products/duplicates/merge \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"productIds": [
"4d3c2b1a-0000-4000-8000-000000000001",
"4d3c2b1a-0000-4000-8000-000000000002"
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
productIds: ['4d3c2b1a-0000-4000-8000-000000000001', '4d3c2b1a-0000-4000-8000-000000000002']
})
};
fetch('https://omnicommerce.ai/api/v1/products/duplicates/merge', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://omnicommerce.ai/api/v1/products/duplicates/merge"
payload = { "productIds": ["4d3c2b1a-0000-4000-8000-000000000001", "4d3c2b1a-0000-4000-8000-000000000002"] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"ok": true,
"apiVersion": "<string>",
"operationId": "<string>",
"status": "accepted",
"data": {
"success": true,
"productIds": [
"<string>"
],
"succeededCount": 4503599627370495,
"failedCount": 4503599627370495,
"items": [
{
"productId": "<string>",
"success": true,
"survivingProductId": "<string>",
"disposition": "survivor",
"error": "<string>"
}
],
"dryRun": true,
"survivingProductId": "<string>",
"survivingProductIds": [
"<string>"
],
"mergedProductIds": [
"<string>"
],
"wouldMergeProductIds": [
"<string>"
],
"groups": [
{
"productIds": [
"<string>"
],
"success": true,
"survivingProductId": "<string>",
"mergedProductIds": [
"<string>"
],
"wouldMergeProductIds": [
"<string>"
],
"error": "<string>"
}
],
"message": "<string>",
"error": "<string>",
"explanation": "<string>"
},
"warnings": [
"<string>"
],
"recommendations": [
"<string>"
],
"links": {},
"error": "<string>"
}Merge Duplicate Products
Merge exact-SKU duplicate products into one master product per group. The master keeps its content, images, price and stock; the group’s other products are archived into it, and orders, reviews, promotions and other catalog references move to the master.
All marketplace listings move to the master, including listings in other stores of the same marketplace. Different listing identities in the same store block the group. No marketplace listing is delisted, rewritten or republished.
Each group commits independently; the response lists every group’s outcome. Sources with inventory history or immutable order composition snapshots must be reconciled before archiving so returns and stock replays keep their targets.
Supports every OmniCommerce marketplace. Variant families, bundles and products in different currencies cannot be merged. A stock-connected product may be kept as master; it cannot be archived into another product. Use preview masterSelections to choose an allowed master.
Authorization
Requires catalog:write. This is a catalog operation with no remote marketplace writes.
Limits
2–20 products and up to 10 groups per request. Pin a reviewed preview with expectedGroups to refuse groups that changed since.
Set dryRun=true to simulate the same transaction and roll it back. The response has data.dryRun=true; succeededCount/failedCount count validation outcomes, mergedProductIds is empty and wouldMergeProductIds lists the planned sources. No product update events or duplicate scan refreshes are emitted. A successful simulation is not a saved merge; real execution validates current data again.
curl --request POST \
--url https://omnicommerce.ai/api/v1/products/duplicates/merge \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"productIds": [
"4d3c2b1a-0000-4000-8000-000000000001",
"4d3c2b1a-0000-4000-8000-000000000002"
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
productIds: ['4d3c2b1a-0000-4000-8000-000000000001', '4d3c2b1a-0000-4000-8000-000000000002']
})
};
fetch('https://omnicommerce.ai/api/v1/products/duplicates/merge', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://omnicommerce.ai/api/v1/products/duplicates/merge"
payload = { "productIds": ["4d3c2b1a-0000-4000-8000-000000000001", "4d3c2b1a-0000-4000-8000-000000000002"] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"ok": true,
"apiVersion": "<string>",
"operationId": "<string>",
"status": "accepted",
"data": {
"success": true,
"productIds": [
"<string>"
],
"succeededCount": 4503599627370495,
"failedCount": 4503599627370495,
"items": [
{
"productId": "<string>",
"success": true,
"survivingProductId": "<string>",
"disposition": "survivor",
"error": "<string>"
}
],
"dryRun": true,
"survivingProductId": "<string>",
"survivingProductIds": [
"<string>"
],
"mergedProductIds": [
"<string>"
],
"wouldMergeProductIds": [
"<string>"
],
"groups": [
{
"productIds": [
"<string>"
],
"success": true,
"survivingProductId": "<string>",
"mergedProductIds": [
"<string>"
],
"wouldMergeProductIds": [
"<string>"
],
"error": "<string>"
}
],
"message": "<string>",
"error": "<string>",
"explanation": "<string>"
},
"warnings": [
"<string>"
],
"recommendations": [
"<string>"
],
"links": {},
"error": "<string>"
}Authorizations
Bearer API key for server-to-server access. Session auth is also supported in first-party UI flows.
Body
Ordered standalone catalog product IDs. Products are grouped by exact SKU; each group merges into one master.
2 - 20 elements1 - 255True runs the same merge transaction and rolls it back, including database reference/constraint validation. No product changes are saved, no mutation events or duplicate refreshes run, and marketplace listings stay unchanged. Requires catalog:write. Omitted/false performs the reviewed merge. This differs from CLI --dry-run, which only prints a request.
Required only for session-authenticated calls. API credentials use their own organization.
Optional master per SKU group, chosen from productIds; at most one per group. Defaults to the first requested product of each group. The master keeps its content, images, price and stock.
1 - 10 elements1 - 255Optional groups from a preview to pin: membership, master (first product) and SKU. Groups that changed or are omitted are not merged.
1 - 10 elementsShow child attributes
Show child attributes
2000Response
Batch processed. data holds groups[] (with survivingProductId, mergedProductIds, error), ordered per-product items[], succeededCount and failedCount. ok is true only when every group merged.