Preview Customer Merge
POST/api/v2/customers/merge/preview
Preview the effect of merging one customer (secondary) into another (primary) without changing any data. Returns, per related record type, the number of records currently attached to the secondary customer that would be reassigned to the primary: sales orders (sales_orders), sales credits (sales_credits), customer SKU mappings (customer_sku_mappings), order document extractions (sales_order_ocr_extractions), and linked QuickBooks customer records (qbo_customers).
customers:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Use this before calling Merge Customers so the operator can review what will move.
Body fields:
- primary_customer_id (integer, required): the customer that will be kept; must reference an existing customer.
- secondary_customer_id (integer, required): the customer that will be merged 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
- 200
- 401
- 403
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.