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 is part of the Core API and is called two ways, depending on which IDs you are passing.

When passing Tulip IDs, the API should be called in the following format:

https://<Tulip Cloud URL>/v2/crm/customers/<PRIMARY CUSTOMER ID>/merge

When passing External IDs, the API should be called in the following format:

https://<Tulip Cloud URL>/v2/crm/customers/<PRIMARY CUSTOMER ID>/merge_by_external_id

With the secondary (to be merged) customers provided as parameters as shown in the example below.

Example Request

curl --location --request PUT 'https://<Tulip Cloud URL>/v2/crm/customers/2154/merge'
    --header 'Accept-Language: en'
    --header 'Content-Type: application/json'
    --header 'Authorization: Bearer <TOKEN>'
    --data-raw '{"ids": [2155, 2156, 2157]}'

curl --location --request PUT 'https://<Tulip Cloud URL>/v2/crm/customers/external_id_2154/merge_by_external_id'
    --header 'Accept-Language: en'
    --header 'Content-Type: application/json'
    --header 'Authorization: Bearer <TOKEN>'
    --data-raw '{"ids": ["external_id_2155", "external_id_2156", "external_id_2157"]}'

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 →