"merged" customer_id confusion

Questions
1

I have a yoga studio system. Students can buy individual class cards or subscriptions.
I use the customer API get a square customer id for each new student. I save the returned ID in as primary key in my database ‘students’ table.,
I refer to webhooks like ‘payment.created’ and ‘payment.updated’ to track student payments. These webhooks have ‘customer_id’ info. I move info into a ‘studentpayments’ table.
What I now see is that some payment’s ‘customer_id’ has a value that doesn’t match any ‘students’ record.
If I use the API explorer, I can find a record for this unknown square id. The API explorer shows source ‘Merge’
I can manually search my database for the name, email, etc., and usually can find a database record that shows the ORIGINAL square customer_id saved in the database.
If I use the API Customer explorer, I can find that earlier original square record showing the with source ‘Merge’

I see that I was not well informed about Square Customer_IDs
These are not appropriate for database primary keys, as they can be changed arbitrarily with a Square “merge” operation.

So relating ‘studentpayments’ to the orginal customer_id creates a lot of problems. Customer_ids identified in Payment webhooks may not have any info in my database.

I can’t find any API that shows the customer_ids that were merged into Square’s new customer_id.

I was unaware that NEW Square customer records were being createrd by Square outside of my control. I create “customer” updates via API when students change their information, so I haven’t been tracking ‘customer.created’ webhooks.

I assume that there’s a suggested method for handling customer-created webhooks for a merge? Not shown as an individual webhook – It appears to be included a ‘merge’ event found in a custtomer_created webhook? (I don’t see any way to initate a test “CreateCustomer” webhook that includes the context of a customer_merge, however.)

From the documentation on “merge” it t looks like Square treats the new Merged id as the customer primary key? Also apparently deletes customer records with previous ids?

Am I going to have to update all previous database records to reflect this change? Is the previous ‘customer_id’ useless?

Some of our students use the same name, email address, etc. to create different types of studio database accounts (one for subsriptions, another for one-off purchases like workshops, tshirts, etd), with different usernames and passwords, and these got different square customer ids saved in the database as my database primary key. In at least one instance these records were merged to a new customer_id, even though in my view they represent different student records, based on the STUDENT’s desire to have separate records

I need more understanding of

  1. When and how Square decides to merge customer_ids
    This seems to be an internal decision not based on an event my system intiated?

  2. How better to use the merge events? Records deleted even though my database thinks they exist? Similar records I created now must be reflect merged ids?

  3. Whether existing Square payment/subscription and other data reflects the original customer_id or the new merged id

  4. How to find records of all existing customer_ids: the current customer_id and previous ids – since I have not been following along all these ‘customer-created / merged’ webhooks.

It looks like I’ll have to establish a different primary key, and then develop a resolving table “studentSquareIDs” to do much more complicated database selections.

Also from an answer to an earlier question
…/forums/t/merged-customer-id-confusion/22030
you replied:

The merge operation prioritizes older data over newer data. That’s why the old names were retained in the merged profile.

So apparently your merge will alter names/email addresses, etc.? Square decides that 2 customers are the ‘same’, and merge, but decides to use older data instead of newer? Really?

Any thoughts on this that might be helpful?

2

:waving_hand: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

Additional Documentation

Integrate Customer Profiles with Other Services
Payments API Webhooks
Customers API

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

3

Square does indeed merge customer profiles under certain conditions. This typically happens when Square identifies multiple customer profiles for the same customer. For example, if a customer makes a payment without signing in to their account, Square might generate an instant profile. To maintain accurate records, sellers can merge these duplicate profiles from the Customer Directory in the Seller Dashboard or Square Point of Sale.

When a merge operation occurs, Square creates a new profile using aggregated properties from the existing profiles and then deletes the existing profiles. As a result, a merge operation triggers one customer.created event and at least two customer.deleted events. All notifications from a merge include an event_context field with a merge object that contains the IDs of the affected customer profiles.

To track the IDs of customer profiles affected by a merge, you can listen for customer.created events and check whether the notifications contain the event_context.merge field. This method is more efficient than checking customer.deleted events because a merge always creates a single customer profile and the associated merge object contains the IDs of all affected customer profiles.

If you need additional information about the deleted customer profiles, make sure to also subscribe for customer.deleted event notifications, which include the customer object. You cannot retrieve a customer profile after it is deleted.

In terms of your database, it would indeed be advisable to establish a different primary key and develop a resolving table to manage the changes in customer IDs. This would allow you to keep track of all existing customer IDs, both current and previous.

This answer was reviewed by @josh-square.

4

Hey @NemoNoman! As a follow up to the above — it’s correct that deleted customer objects cannot be retrieved. However, if it was deleted as part of a merge operation, attempting to retrieve the deleted customer ID will instead return the new customer ID that it was mapped to.

Let me know if there’s anything else I can clarify!

5

Thanks Josh.
Actually you can help me with some additional information.
My yoga studio uses Square for subscriptions and to sell merchandise, etc. Merchandise sales are made using SQUARE “Item” forms created from the studio ‘Square Dashboard’

My hand-written subscriber system creates database records for yoga subscribers. It uses the Square customer ID because I assumed that was a unique persistent identifier. My program creates a subscriber record and stores first/last name, email address, and card information using the customer_id as the identifier for the subscribers. I provide input forms for my subscribers to make changes (married name, new email, new card, etc), I have added methods for subscribers to use their Square cards to pay for additional classes outside of those included in a subscription.

I created forms for updating the Square data associated with my subscribers My system makes changes to my database, and then uses Square APIs to make Square updates. I use the ORIGINAL cutomer_id as the basis for these updates.

Because I assumed that the customer_id was consistent, I have not added error checking to my Square update calls. I test them in development and once they work they go into production. I have as yet not been aware of any errors.

Checking my webhook database I now see that there have been 68 customer merge events since 1 January.

So now I have concerns. I suppose I must now review all 68 events and try to understand what has been done.

It appears that some of the these merge actions were made merging ‘merch’ type customer records. I don’t know yet if the ‘merch’ and my subscriber database now have ‘merged customers’ – but I now see potential for errors and confusion.

Checking one webhook, I see that my subscriber with customer_id ‘OriginalDxxxxxxxxxx’ now has been merged with ‘SomeOtherIDxxxxxxxxxxx’ creating ‘NewMergeIDxxxxxxxxxxxxx’

I can no longer find the creation data associated with ‘OriginalDxxxxxxxxxx’ or ‘SomeOtherIDxxxxxxxxxxx’ – I can’t see the dates when these records were created, which is most recent, or what info was used to create them. So I have concerns about using the info in
‘NewMergeIDxxxxxxxxxxxxx’

It is very possible that ‘OriginalDxxxxxxxxxx’ was created by my system when customer subscribed, and that ‘SomeOtherIDxxxxxxxxxxx’ was created when the customer bought merch. It is very possible that this customer used different names or cards or email addresses when buying merch.

  1. Why was this merge event triggered?
  2. Which personal data was used for ‘NewMergeIDxxxxxxxxxxxxx’?
    Which names, email, etc were kept and which discarded if there were differences between ‘OriginalDxxxxxxxxxx’ and ‘SomeOtherIDxxxxxxxxxxx’?
  3. If ‘OriginalDxxxxxxxxxx’ and ‘SomeOtherIDxxxxxxxxxxx’ were created based on different credit cards, are those cards now included with ‘NewMergeIDxxxxxxxxxxxxx’?
  4. If the customer uses my form to change subscriber name or email, and I then use the ‘Update Customer’ API to update Square with ‘OriginalDxxxxxxxxxx’ as customer_id, what happens? Is email really the primary key for customer records?
  5. Is the email address retained by’NewMergeIDxxxxxxxxxxxxx’ now used for emails sent from square, like subscription invoice updates?

I really don’t know all the questions I should be asking about this. I have just opened up a can of worms.