Customers API

Use Customer Webhooks

Use webhooks to receive notifications when customer profiles are created, updated, or deleted. Webhooks help streamline the process of synchronizing customer data across Square and third-party applications. Webhooks also enable custom integration scenarios that respond to changes in near real time. For example, when a customer signs up for a new account, Square creates a customer profile, which triggers an event notification. After your application receives the notification, it can respond to the event. For example, your application can send a coupon to the new customer to use for a purchase.

For information about general webhooks requirements, components, and processes, see Square Webhooks.

How customer event notifications work Permalink Get a link to this section

Webhooks make it possible for Square to notify you when customer events occur, so you do not need to rely only on polling for changes. If you regularly poll the Customers API to synchronize stored customer data, you can use webhooks and increase the time between your polls.

A webhook is a subscription that registers a notification URL and the events that you want to be notified about. You can configure webhooks for the following customer events.

EventDescription
customer.createdA customer profile is created, including when customer profiles are merged into a new customer profile.
customer.deletedA customer profile is deleted, including when customer profiles are merged into a new customer profile.
customer.updatedAn attribute on a customer profile is changed, except for the following:
  • cards (deprecated)
  • segment_ids

When an event occurs, Square collects data about the event, creates a notification, and sends the notification as a POST request to the URL of all webhooks that are subscribed to the event.

The following actions can invoke customer events:

Customer profile merge events Permalink Get a link to this section

The use of different tools or information silos might produce duplicate 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 duplicate customer profiles from the Customer Directory in the Square Seller Dashboard or POS application. In a merge operation, Square creates a new profile using aggregated properties from the existing profiles and then deletes the existing profiles. As a result, merge operations trigger notifications for both customer.created and customer.deleted events. For more information, see Notifications for customer profile merge events.

Requirements and limitations Permalink Get a link to this section

The following requirements and limitations apply to webhooks for customer events:

  • Applications that use OAuth must have CUSTOMERS_READ permission to receive notifications about customer events.

  • You must protect personally identifiable information (PII) and other sensitive customer information that you receive in the notification. This includes information such as customer name, address, and phone number. Unless manually added in a note or other field, credit card information is never included in notification data. For more information, see Best Practices for Collecting Information.

  • The following operations do not invoke customer event notifications:

    • Changing a customer's membership in customer segments.

    • Creating or deleting customer cards. However, you can subscribe to Cards API events and Gift Cards API events.

    • Changing customer-related integrations from other Square APIs, such as the Payments API, Orders API, Loyalty API, or Subscriptions API. For example, changing the customer ID on an order does not invoke a customer.updated notification.

    Square does not send notifications for events that fail.

For general webhook requirements and limitations, see Square Webhooks.

Subscribe to customer events Permalink Get a link to this section

To subscribe for notifications about customer events, you can configure webhooks for your Square application. A webhook registers the URL that Square should send notifications to, the events you want to be notified about, and the Square API version.

To configure a webhook

  1. In the Developer Dashboard, open the application to which you want to subscribe.

  2. In the navigation pane, choose Webhooks.

  3. At the top of the page, choose Sandbox or Production. You should use the Sandbox environment for testing.

  4. Choose Add Endpoint, and then configure the endpoint:

    1. For Webhook Name, enter a name such as Customers Webhook.

    2. For URL, enter your notification URL. If you do not have a working URL yet, you can enter https://example.com as a placeholder.

    3. Optional. For API Version, select a Square API version. By default, this is set to the same version as the application. Customer webhooks are available starting in version 2021-02-26.

    4. For Events, select customer.created, customer.deleted, and customer.updated. If you want to receive notifications about other events at the same URL, select them or configure another endpoint.

    5. Choose Save.

    Note

    In the Production environment, ignore the Enable Webhooks setting on the Webhooks page. This setting applies to webhooks for Connect v1 APIs (deprecated).

To validate your webhook configuration

You can send a generic notification from the Developer Dashboard to validate that your webhook is configured correctly.

  1. On the Webhooks page for your application, choose the webhook that you want to test.

  2. On the Endpoint Details pane, choose More, and then choose Send Test Event.

  3. Select an event, and then choose Send. If the endpoint is configured correctly, the Send Test Event dialog displays the response code and notification body.

Receive customer event notifications Permalink Get a link to this section

When customer profiles in your account are created, updated, deleted, or merged, Square sends a notification to any webhooks that are subscribed to the corresponding event.

To handle notifications, applications typically perform the following steps:

  1. Validate the authenticity of the notification.

  2. Respond with an HTTP 2xx response code within 10 seconds of receiving the notification.

  3. Inspect, process, store, or forward the notification.

  4. Synchronize customer data or take some other action based on the event.

The body of the notification is a JSON object that contains the following properties.

PropertyDescription
merchant_idThe ID of the seller whose directory contains the affected customer.
typeThe type of event:
  • customer.created
  • customer.deleted
  • customer.updated
event_idThe unique ID of this event, used for idempotency support.
created_atA timestamp of when the event occurred. For example: 2021-07-30T21:59:15.286Z
dataInformation about the affected customer, represented by one of the following objects, depending on the event type:
  •  CustomerCreatedWebhookData
  •  CustomerDeletedWebhookData
  •  CustomerUpdatedWebhookData
The data.object property represents the customer resource and includes attributes defined for the customer, except:
  • cards (deprecated)
  • segment_ids
If your use case requires the full customer resource, use the customer ID from the notification to call the RetrieveCustomer endpoint.

Notifications for customer.created events Permalink Get a link to this section

A customer.created event is invoked when a customer profile is created. The following is an example event notification:

{
  "merchant_id": "KTDR6CEPCWXYL",
  "type": "customer.created",
  "event_id": "226ea61b-476d-4487-84c8-f68b142976f8",
  "created_at": "2021-01-21T19:00:04Z",
  "data": {
    "type": "customer",
    "id": "YBE4YXMS1CT7K4HP1KTXYFBWZ0",
    "object": {
      "customer": {
        "created_at": "2021-01-21T19:00:04.693Z",
        "creation_source": "THIRD_PARTY",
        "email_address": "jdoe@email.com",
        "family_name": "Doe",
        "given_name": "Jane",
        "id": "YBE4YXMS1CT7K4HP1KTXYFBWZ0",
        "phone_number": "+12065551212",
        "preferences": {
          "email_unsubscribed": false
        },
        "updated_at": "2021-01-21T19:00:04Z",
        "version": 0
      }
    }
  }
}

Note

The following fields are removed from the returned customer object in customer.created notifications: cards (deprecated) and segment_ids.

Notifications for customer.created events from merge operations also include an event-context object. For more information, see Notifications for customer profile merge events.

Notifications for customer.deleted events Permalink Get a link to this section

A customer.deleted event is invoked when a customer profile is deleted. The following is an example event notification. Notifications for delete events contain "deleted": true.

{
  "merchant_id": "KTDR6CEPCWXYL",
  "type": "customer.deleted",
  "event_id": "3af6a667-34cf-42ca-bd76-96b637d8e67f",
  "created_at": "2021-01-21T19:46:09Z",
  "data": {
    "type": "customer",
    "id": "YBE4YXMS1CT7K4HP1KTXYFBWZ0",
    "deleted": true,
    "object": {
      "customer": {
        "creation_source": "THIRD_PARTY",
        "email_address": "jdoe@email.com",
        "family_name": "Doe",
        "given_name": "Jane",
        "id": "YBE4YXMS1CT7K4HP1KTXYFBWZ0",
        "phone_number": "+12065551212",
        "preferences": {
          "email_unsubscribed": false
        },
        "version": 11
      }
    }
  }
}

Note

The following fields are removed from the customer object in customer.deleted notifications: cards (deprecated), group_ids, and segment_ids.

Notifications for customer.deleted events from merge operations also include an event-context object. For more information, see Notifications for customer profile merge events.

Notifications for customer.updated events Permalink Get a link to this section

A customer.updated event is invoked when a customer profile is updated, except when changes are made to the following attributes:

  • cards (deprecated)

  • segment_ids

The following is an example event notification:

{
  "merchant_id": "KTDR6CEPCWXYL",
  "type": "customer.updated",
  "event_id": "8478cc17-a7b9-40e6-b5fa-692e58794ff5",
  "created_at": "2021-01-21T19:42:51Z",
  "data": {
    "type": "customer",
    "id": "YBE4YXMS1CT7K4HP1KTXYFBWZ0",
    "object": {
      "customer": {
        "created_at": "2021-01-21T19:00:04.693Z",
        "creation_source": "THIRD_PARTY",
        "email_address": "jdoe@email.com",
        "family_name": "Doe",
        "given_name": "Jane",
        "group_ids": [
          "3MEP3VM842KQZXQ9WSBJRTX73H"
        ],
        "id": "YBE4YXMS1CT7K4HP1KTXYFBWZ0",
        "phone_number": "+12065551212",
        "preferences": {
          "email_unsubscribed": false
        },
        "updated_at": "2021-02-10T13:02:15Z",
        "version": 3
      }
    }
  }
}

Note

The following fields are removed from the customer object in customer.updated notifications: cards (deprecated) and segment_ids.

To discover which customer profile attributes changed, compare the updated customer resource in the notification with your local copy of the customer profile.

If customer.updated events for the same customer profile occur concurrently, Square compares their version numbers and sends a webhook notification for the latest version only. If you receive multiple customer.updated notifications for the same customer profile before you process them, you can use the version field of the customer object to determine the latest version.

Notifications for customer profile merge events Permalink Get a link to this section

A merge operation creates a new customer profile using aggregated properties from two or more existing profiles, and then deletes the existing profiles. As a result, a merge triggers a combination of notifications:

  • A customer.created event for the new customer profile.

  • A customer.deleted event for each existing customer profile that was merged and deleted.

All notifications from a merge include an event_context field that contains the IDs of the affected customer profiles.

"event_context": {
  "merge": {
    "from_customer_ids": [
      // IDs of existing customer profiles that were merged and deleted
    ],
    "to_customer_id": // ID of new customer profile
  }
}

All notifications sent for a particular merge operation contain the same merge object.

Did you know?

If you only want 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 create a single customer profile and a 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.

Example notifications from a merge operation Permalink Get a link to this section

In this example scenario, two customer profiles are merged, so Square sends three notifications: one customer.created notification and two customer.deleted notifications.

The customer.created notification is sent when the new profile is created. Note the following customer profile attributes:

  • creation_source is set to MERGE.

  • note lists the merge date and any non-transferable attributes.

The following is an example customer.created notification:

{
  "merchant_id": "KTDR6CEPCWXYL",
  "type": "customer.created",
  "event_id": "04d6e69f-d3dc-4fb7-a891-beb0cf7e8457",
  "created_at": "2021-01-21T23:10:38Z",
  "data": {
    "type": "customer",
    "id": "A9641GZW2H7Z56YYSD41Q12HDW",
    "object": {
      "customer": {
        "address": {
          "address_line_1": "123 Main Street",
          "administrative_district_level_1": "WA",
          "country": "US",
          "locality": "Seattle",
          "postal_code": "98104"
        },
        "birthday": "1998-09-01T00:00:00-00:00",
        "company_name": "ACME Inc",
        "created_at": "2021-01-21T22:59:16.271Z",
        "creation_source": "MERGE",
        "email_address": "johndoe@acme.com",
        "family_name": "Doe",
        "given_name": "John",
        "group_ids": [
          "3MEP3VM842KQZXQ9WSBJRTX73H"
        ],
        "id": "A9641GZW2H7Z56YYSD41Q12HDW",
        "note": "Favorite: Double-shot Iced Americano\n// Merged on 2021/01/21. Following fields were not transferred to the current customer:\nPhone Number: 14065551212",
        "phone_number": "14065551112",
        "preferences": {
          "email_unsubscribed": false
        },
        "updated_at": "2021-01-21T23:10:39Z",
        "version": 0
      },
      "event_context": {
        "merge": {
          "from_customer_ids": [
            "20R574N4D0VP74N56QTRSKDJ9C",
            "P3ZRDK895X1JQCX9D3C4KEF4YG"
          ],
          "to_customer_id": "A9641GZW2H7Z56YYSD41Q12HDW"
        }
      }
    }
  }
}

Two customer.deleted notifications are sent when the two existing profiles are merged and then automatically deleted as part of the merge operation. The following are example event notifications:

  • Example for existing customer profile 1:

    {
      "merchant_id": "KTDR6CEPCWXYL",
      "type": "customer.deleted",
      "event_id": "1cad466e-400a-40a8-84a6-6b8c278acc95",
      "created_at": "2021-01-21T23:10:38Z",
      "data": {
        "type": "customer",
        "id": "P3ZRDK895X1JQCX9D3C4KEF4YG",
        "deleted": true,
        "object": {
          "customer": {
            "address": {
              "address_line_1": "123 Main Street",
              "administrative_district_level_1": "WA",
              "country": "US",
              "locality": "Seattle",
              "postal_code": "98104"
            },
            "birthday": "1998-09-01T00:00:00-00:00",
            "company_name": "ACME Inc",
            "creation_source": "DIRECTORY",
            "email_address": "johndoe@acme.com",
            "family_name": "Doe",
            "given_name": "John",
            "id": "P3ZRDK895X1JQCX9D3C4KEF4YG",
            "note": "Favorite: Double-shot Iced Americano",
            "phone_number": "14065551112",
            "preferences": {
              "email_unsubscribed": false
            },
            "version": 10
          },
          "event_context": {
            "merge": {
              "from_customer_ids": [
                "20R574N4D0VP74N56QTRSKDJ9C",
                "P3ZRDK895X1JQCX9D3C4KEF4YG"
              ],
              "to_customer_id": "A9641GZW2H7Z56YYSD41Q12HDW"
            }
          }
        }
      }
    }
    
  • Example for existing customer profile 2:

    {
      "merchant_id": "KTDR6CEPCWXYL",
      "type": "customer.deleted",
      "event_id": "ca6a30a6-3c58-49ec-b626-5ed733e861ad",
      "created_at": "2021-01-21T23:10:38Z",
      "data": {
        "type": "customer",
        "id": "20R574N4D0VP74N56QTRSKDJ9C",
        "deleted": true,
        "object": {
          "customer": {
            "creation_source": "LOYALTY",
            "id": "20R574N4D0VP74N56QTRSKDJ9C",
            "phone_number": "14065551212",
            "preferences": {
              "email_unsubscribed": false
            },
            "version": 4
          },
          "event_context": {
            "merge": {
              "from_customer_ids": [
                "20R574N4D0VP74N56QTRSKDJ9C",
                "P3ZRDK895X1JQCX9D3C4KEF4YG"
              ],
              "to_customer_id": "A9641GZW2H7Z56YYSD41Q12HDW"
            }
          }
        }
      }
    }
    

Test your webhooks Permalink Get a link to this section

To test your webhook with actual resources, you can make changes to the customer profiles in your account. Make sure to test with the same environment (Sandbox or Production) that you registered for the webhook.

The following are some ways you can trigger customer event notifications.

Test from the Seller Dashboard

  1. Open your Seller Dashboard.

  2. In the navigation pane, choose Customers, and then create, update, delete, or merge customers.

    To merge profiles, select two or more customers, and then choose Merge. For more information, see Duplicates.

Test from API Explorer

Sign in to API Explorer and choose your Sandbox or Production environment. Then, call the following Customers API endpoints as needed to test your webhook:

Test using cURL

Send cURL requests to Customers API endpoints. For more information, see the following documentation:

Note

You can also send a generic test notification from the Developer Dashboard.

You should receive notifications for customer events that you subscribe to. Square does not send notifications for events that fail.

For information about troubleshooting Square Webhooks, see Webhooks Troubleshooting.