Skip to main content
POST
Merge customers
For each field, field_sources and custom_field_sources select the customer that gives the value. A field that you do not name keeps the survivor value. When that value is empty, the field gets the first duplicate value. The survivor always keeps its default currency, and you cannot undo a merge. Side effects
  • DualEntry moves the records, attachments, payment methods and company access of the duplicate customers to the survivor.
  • DualEntry archives each duplicate customer and sets its merged_into_id to the survivor.
  • When the survivor takes the name of a duplicate, DualEntry adds (merged into <survivor code>) to the name of that duplicate.
  • When the survivor has no Stripe mapping, DualEntry moves the Stripe mapping of a duplicate to the survivor. DualEntry removes all other integration mappings of the duplicates.
  • DualEntry sends one core.customer/merged webhook event for each duplicate customer.
Additional validations
  • Fails with 422 when a customer has child customers or is an intercompany customer. It also fails when the customers have different subsidiaries, tax registration numbers, or VAT or GST registrations.
  • Fails with 422 when the merge must move or read more than 20,000 rows. It also fails when your API key cannot access a company where the duplicates have records. The same rule applies to a company that the merge adds to the company access of the survivor. A selected company_access must include each company where the customers have records.
  • Fails with 422 when a duplicate customer has transactions in a locked AR period. Bill, direct expense and vendor credit lines that bill a customer use the AP lock.
  • Fails with 422 when field_sources or custom_field_sources selects a customer that is not in the merge, or a custom field that does not exist.
  • Fails with 409 when another merge uses one of the customers.
  • Fails with 417 when the merge does not finish in 25 seconds. No data changes.

Authorizations

X-API-KEY
string
header
required

Headers

Idempotency-Key
string

Optional. A unique value (a UUID works well) identifying this operation. If the request is repeated with the same key, the original response is replayed instead of the operation running again, so a retry cannot create a duplicate record. Results are replayable for 48 hours. Reusing a key with a different request body returns 422.

Maximum string length: 255

Body

application/json
target_customer_id
integer
required

The ID of the customer that stays. It keeps its ID, code and records.

source_customer_ids
integer[]
required

The IDs of the duplicate customers. The merge moves their records to the survivor, then archives them.

Required array length: 1 - 25 elements
field_sources
Field Sources · object

For each field, the ID of the customer that gives the value to the survivor. A field that you do not name keeps the survivor value. When that value is empty, the field gets the first duplicate value.

custom_field_sources
Custom Field Sources · object

For each custom field ID, the ID of the customer that gives the value to the survivor.

Response

OK

target_customer_id
integer
required
merged_customer_ids
integer[]
required
moved_counts
Moved Counts · object
required
applied_field_sources
Applied Field Sources · object
required
applied_custom_field_sources
Applied Custom Field Sources · object
required
success
boolean
default:true