Skip to main content

Merge Customers

POST 
/api/v2/customers/merge

Merge the secondary customer into the primary customer. This is a destructive operation performed in a single transaction:

Required scope: customers:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

  • All related records are reassigned from the secondary to the primary customer: sales orders, sales credits, quotes, order document extractions, artwork, store credit entries, loyalty transactions, house-account (on-account) transactions, gift cards, saved payment methods, AR communications, customer SKU mappings, customer pricing, B2B price group membership, addresses, contacts, tags, portal buyers/saved lists/carts/approvals/feed keys/account applications, channel customer mappings, and QuickBooks, Xero, Shopify B2B location and Magento customer links. Store credit, loyalty and house-account balances are the sum of their ledgers, so the combined balance is preserved (running balance_after values are re-chained). Where the primary already holds a conflicting row (same customer SKU, same price tier, same address, same tag, an existing portal cart, etc.) the primary's row is kept and the secondary's stays on the archived customer; the only primary contact / default card stays the primary's.
  • Contact fields (email, company, phone, fax, tax number, default shipping/billing address) are copied from the secondary onto the primary only where the primary's value is empty; existing primary data is never overwritten.
  • The secondary customer is archived.
  • A merge log is written capturing a snapshot of both customers and the per-table reassignment counts (fk_moves).

The returned merge_log_id can be used to reverse the merge within 30 days via Undo Customer Merge. The request fails with 422 if the secondary customer is already archived or the primary customer is archived.

Body fields:

  • primary_customer_id (integer, required): the customer to keep; must reference an existing customer.
  • secondary_customer_id (integer, required): the customer to merge away; must reference an existing customer and differ from primary_customer_id.

Authentication: Requires Bearer token with the customers read/write scope and the customer merge permission.

Request​

Responses​

OK

Response Headers
    Content-Type