Customer Merge

Tulip provides a way to merge customers records together. This is a common when an external system is consolidating customer records that may be duplicates. When the external system decides that two records actually refer to the same customer, the Tulip merge endpoint can be called in order to request that Tulip merges those records as well, into one (primary) record. When called, the merge endpoint instructs Tulip to internally handle the merging of data and references to other data within Tulip.

Merge API Endpoints

The customer merge API endpoint leverages the following request URL: /api/{version}/crm/customers/{id}/merge

Example Request

curl --location --request POST 'https://tulip-staging-mystore.tulipretail.com/api/2025-04/crm/customers/external_id_2158/merge'
    --header 'Accept-Language: en'
    --header 'Content-Type: application/json'
    --header 'Authorization: Bearer <TOKEN>'
    --data-raw '{"mergeWithCustomerIds": ["external_id_2155", "external_id_2156", "external_id_2157"]}'

You can find API documentation on this endpoint here: https://docs.tulip.com/apidocs/aerial?version=2025-04#post-/api/2025-04/crm/customers/-id-/merge

How does it work?

The endpoint requires a call to our API passing in the primary record (the record you’d like to be the defacto record) and secondary records that you’d like to merge into it.

It will merge the following items from the secondary record to the new primary record.

  • Order History
  • Clienteling Followups associated with this Customer
  • All Customer Notes (Notes, Phone, Opt-In Records, Video, Social)
  • Message History
  • Customer Preferences
  • Product Shares

It will also remove any duplicates if it finds them in the Customer-Associate associations.

It will then mark the secondary records as disabled. The primary record will be updated with a new updated_at_timestamp.

It does not merge following:

  • Emails
  • Addresses
  • Phones
  • Social Profiles
  • Loyalty Tiers

It does not merge these items because we expect the new primary customer to already have had these supplied in its original definition, the internal merge tool instead focuses on merging data that is only internal to Tulip.

← Introduction
Getting started →