Question about auto "merged" customers

Questions
1

My yoga studio system uses Square for subscriptions and some product purchases. The studio also uses Square POS for some purchases.

The studio offers online-only livestreams, providing access through a database “person” record that includes username and password. The studio offers some “trial” and “guest” online subscriptions at no cost. These often become the source for paid subscriptions.

When a trial or guest subscription is saved to the person database table, I also create a square customerid for the person and save that to the record.

Let’s explore this problem as an example: I hope you can explain what happened and how I can prevent or correct confusion from merged customers.

Consider Mary Doe (not her real name)
She became a ‘guest’ subscriber. I saved her username ‘Marydoe’, password, email, and square id.

Rather than asking us to help her upgrade to a paid subscription, she tried to create a new paid subscription from our subscription page. But that page told her desired username ‘Marydoe’ was already in use. A teacher changed her username to ‘Marydoexxx’ and changed her first and lastname to Maryxxx Doexxx’. With these changes, Mary Doe registered as a paid subscriber with a DIFFERENT squareid. (Please note that Mary Doe never provided a credit card for the first ‘guest’ subscription.)

Mary Doe emailed me saying that her Square invoices for her paid subscription were calling her MaryXXX DoeXXX.

I used the API to check her customer record for the paid subscription, and found that it had been automatically merged.

The response showed:

"given_name": "Maryxxx",  
"family_name": "Doexxx",
    "email_address": "marydoe@xxxxx",
    "note": " Merged on 09/14/2023. Following fields were not transferred to the current customer:First Name: Mary Last Name: Doe",
    "preferences": {
      "email_unsubscribed": false
    },
    "creation_source": "MERGE",

(Again, please note that Mary Doe never provided a credit card for the first ‘guest’ subscription. The CURRENT merged record retains her NEWER square id, but uses the OLD first and last names)

  1. I don’t understand why this merge was done (?? same email ??)
  2. I don’t know why the merge decided that unwanted OLD squareid names should supercede the NEW squareid record.
  3. Is there an API call I can use to find all “merged” customers, and verify the information?

Can you please help me undstand steps to take to identify and stop this confusion.

I explored whether a merge event can be included in webhook subscription, but I can’t find a “merge” event?

2

:wave: 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
Customers API
Invoices 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 automatically merges customer profiles when it detects duplicates. In this case, it seems like the system identified the two profiles of Mary Doe as duplicates because they shared the same email address. When a merge operation occurs, Square creates a new profile using aggregated properties from the existing profiles and then deletes the existing profiles. This triggers one customer.created event and at least two customer.deleted events.

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

To track merged customer profiles, you can subscribe to the customer.created webhook event and check whether the notifications contain the event_context.merge field. This field is included when the customer profile is created from a merge operation and contains the IDs of all affected customer profiles.

Unfortunately, there isn’t a specific “merge” event you can subscribe to, and there isn’t a direct API call to find all merged customers. However, you can use the customer.created webhook event as described above to track when merges occur.

To prevent this confusion in the future, you could implement a check in your system before creating a new customer profile. Use the SearchCustomers endpoint to search by email address or phone number to determine whether a profile for the customer already exists. If a profile exists, you can update it instead of creating a new one. This should help prevent the creation of duplicate profiles and subsequent automatic merges.

This answer was reviewed by @Bryan-Square.

4

Can somebody please point out to the develoment team that merging is using some crazy logic?

I can’t be the only developer who creates new Customer records, and new card records for those customers by capturing the created Square IDs in a database for reuse.

In this case, I created a whole new customer using the API Create Customer Endpoint. The API handed me a Customer ID and I saved it. My DB records show name as MARY DOE.

The merge found a customer record from 2+ years ago, and decided to update the new Square ID with THOSE Names. What was the LOGIC for that? People stop subscriptions, get married, change genders, etc., and new names, and decide to subscribe again. To them, and to me, those are new persons becoming customers. The old persons have passed on. Now Square decides to bring them back to life – and negate the new values?

Yet unless I happen to watch the customer.created end point for a MERGE flag, and then MANUALLY use the NEWLY CREATED CUSTOMER ID to manually change previously created names the customer’s OLD INFO will be used in Square messaging.

What you’re REALLY telling me is that EMAIL ADDRESSES are somehow regarded as unique keys, and any email address previously associated with a customer presents a collision opportunity.

ALSO, since some customers are created through card swipes, entering emails directly into SQUARE without using my code’s API,

It sounds like I have to create a method to search existing Square records for a new customer’s email before submitting any new data like name, address, etc. (??)

5

Can you tell me when the merge decision happens? That is to say

Does square upload the info, create and return a new square id after first merging the data?

Or does the merge activity happen at some later time?

If the merge happens immediately on upload, I can then just use the newly returned Customer ID and update the names, addresses etc immediately without checking – An Immediate update for every new customer, but it would coordinate database with Square data. Not a great solution, but pretty easy to do.

If the merge happens at some later time, I’ll have to watch new customer created webhooks, check for a merge, try to figure out which data is which and hope to update before Square starts sending messages to the customer.