Customers API

Applies to: Customers API | GraphQL | Customer Custom Attributes API | Cards API | Gift Cards API

Learn about the Customers API and how to manage customer profiles.

The Square Customer Directory is a customer relationship management (CRM) tool where Square sellers store customer information, analyze customer interactions and activity, and more. Each customer has a corresponding customer profile — a record of the customer's contact and personal information (such as name, email address, phone number, and birthday) and supplemental information (such as the groups or segments the customer belongs to). Customer profiles are created through Square APIs, the Square Dashboard, Square Point of Sale, and other Square products or experiences.

The Customers API lets you create and manage customer profiles for Square sellers, including memberships in customer groups. The Customers API is often used with other Square APIs, Square products, and third-party tools to provide robust experiences for sellers and their customers. The lean and flexible interface makes it easy to integrate custom functionality into eCommerce and other experiences, typically across analytics, marketing, loyalty, and personalization channels.

Examples of activities you can perform using the Customers API include:

• Keeping customer records for a Square seller account.
• Synchronizing customer data with the Customer Directory by using webhooks and polling for changes.
• Searching for customers using supported query filters.
• Integrating customer data with other Square services to facilitate the customer purchasing experience.

• OAuth permissions - Applications that use OAuth must have appropriate CUSTOMER_READ or CUSTOMER_WRITE access permissions to manage customer profiles. For more information, see Permissions Reference for the Customers API and OAuth API.

• Collecting and storing PII - You must obtain permission from customers before you store their information. You must protect personally identifiable information (PII) and other sensitive information, such as customer name, address, and phone number. Abuse of customer contact information might result in your application being disabled without notice. For more information, see Best Practices for Collecting Information.

• Avoiding duplicate customer profiles - The CreateCustomer and BulkCreateCustomers endpoints don't check for duplicate records during profile creation. To avoid creating duplicate profiles, call the SearchCustomers endpoint and search by phone number, email address, or reference ID to determine whether a profile of the customer already exists. For more information, see Search for Customer Profiles.

• Searching the Customer Directory - The SearchCustomers endpoint doesn't support searching by name, location, or the employee who created the customer profile. For information about supported search query filters, such as email address and phone number, see Search for Customer Profiles.

• Customer linking limitation - Orders made from Square Online stores might not include a customer_id when retrieved from the Orders API, so you shouldn't rely on this field for your integration. Instead, consider using the customer_id field of the corresponding payment. For more information, see Customer assignments for orders and payments.

• Incomplete order history for merged customer profiles - When a customer ID is changed as a result of a merge operation, searching for orders using the new customer ID doesn't currently return any orders made using a previous customer ID. For more information, see Customer assignments for orders and payments.

• Accessing instant profiles that have no public information - Under certain conditions, Square might create instant profiles that don't have public information (such as a given name, family name, email address, phone number, or company name). For example, if a customer doesn't provide an email address or phone number at the time of purchase, Square creates a new Customer object to associate with the Payment object for the purchase. Square uses these Customer objects for activities such as tracking repeat purchases.

  Instant profiles that don't contain public information cannot be viewed or accessed from the Square Dashboard. In addition, this type of instant profile isn't returned in a ListCustomers or SearchCustomers response, even if the creation_source search query filter is set to INSTANT_PROFILE. However, if you have the customer ID, you can use it to call RetrieveCustomer, UpdateCustomer, DeleteCustomer, BulkRetrieveCustomers, BulkUpdateCustomers, BulkDeleteCustomers, or SearchOrders.

• Rate limiting - If your application sends a high number of calls to Square APIs in a short period of time, you should make sure to handle potential 429 rate limiting errors. For more information, see Rate limiting errors.

• Customer tax IDs - For sellers in France, Ireland, Spain, and the United Kingdom, customer profiles can include a tax_ids field that contains the EU VAT identification number of the customer. The following excerpt shows an example customer profile that includes the tax_ids field:

  {
    "customer": {
      "id": "TNQC0TYTWMRSFFQ157KK4V7MVR",
      "created_at": "2020-03-23T20:21:54.859Z",
      "updated_at": "2021-07-14T18:25:21.342Z",
      ...
      "tax_ids": {
        "eu_vat": "IE3426675K"
      }
    }
  }

  Note the following considerations:

  • If tax_ids is specified in CreateCustomer, UpdateCustomer, BulkCreateCustomers, or BulkUpdateCustomers requests in other countries, Square returns a 400 BAD_REQUEST error for Square API version 2021-10-20 or later. For earlier versions, Square ignores this field.
  • Square doesn't verify that the eu_vat identification number is a valid tax ID.
  • Square doesn't automatically merge customer profiles that explicitly specify different eu_vat identification numbers.
  • You can call RetrieveMerchant if you want to check the country of the seller account before attempting to set the tax_ids field.

• Unsupported first-party features - The Customers API doesn't support all customer profile attributes or all features that are available in the Square products, such as the Square Dashboard. For example:

  • Email or text messages - Sellers can send email or text messages directly to a customer from the Square Dashboard (in the production environment only). The Customers API cannot be used to send email or text messages.

  • Notes with reminders - The rich notes that sellers can create in the Square Dashboard aren't included in the Customer object. However, the API does provide an optional note field that displays on the Personal Information card in the Square Dashboard.

  • Private customer feedback - The private feedback that customers can provide from an emailed receipt isn't included in the Customer object. For more information about this feature, see Private customer feedback you can work with.

  • Marketing campaign email preferences - The email_unsubscribed preference indicates whether the customer has unsubscribed from marketing campaign emails. A value of true means that the customer has opted out of email marketing from the current Square seller or from all Square sellers. This value is read-only from the Customers API. For information about how customers can set their preferences, see How Customers Can Unsubscribe From Square Marketing Emails.

• Activate Square account for payment processing - Before you can use Square APIs to process payments, your Square account must be fully activated and enabled for payment processing. If you haven't enabled payment processing on your account (or if you're not sure), visit squareup.com/activation.

You can use Customers API endpoints to perform the following operations in a seller account.

The following endpoints are used to manage customer profiles:

• CreateCustomer - Create a single customer profile.
• UpdateCustomer - Update a single customer profile.
• DeleteCustomer - Delete a single customer profile.
• BulkCreateCustomers - Create multiple customer profiles.
• BulkUpdateCustomers - Update multiple customer profiles.
• BulkDeleteCustomers - Delete multiple customer profiles.

The following endpoints are used to retrieve customer profiles:

• RetrieveCustomer - Retrieve a customer using the customer ID.
• BulkRetrieveCustomers - Retrieve multiple customer profiles using customer IDs.
• ListCustomers - List the customer profiles. You can also use the count query parameter to get the seller's total customer count.

The following endpoint is used to search for customer profiles:

• SearchCustomers - Search for customer profiles using one or more query filters.

The following endpoints are used to manage customer group membership:

• AddGroupToCustomer - Assign a group membership to a customer profile.
• RemoveGroupFromCustomer - Remove a group membership from a customer profile.

The Customers API works with the following primary data types:

• Customer - A single customer profile that contains contact and other personal information such as name, address, email, and phone number.
• Address - A collection of string fields that represent a physical address.
• CustomerGroup - A group of customer profiles whose membership is explicitly defined.
• CustomerSegment - A group of customer profiles whose membership is dynamically defined by filter criteria.
• CustomerPreferences - A customer's preference for receiving marketing emails and contains a single field that can have a true or false value.

A Customer object requires at least one of the following attributes:

• A first or last name.
• The name of the company where the customer works.
• An email address, which must have the @ symbol and a valid domain.
• A phone number, which must meet validation criteria.

Customer objects might also contain other attributes, such as:

• An address.
• A note about the customer. This note field is separate from the rich Notes feature in the Square Dashboard, which doesn't provide any API access.
• A reference ID to associate the customer with an entity in another system.
• Lists of the IDs of the customer groups and customer segments the customer belongs to.

Customer objects can be associated with a collection of custom attributes that store properties that aren't natively available on the object.

Built-in integration between customers and other Square APIs is typically surfaced through a customer_id field on various objects. For example, when present on an Order, the customer_id field contains the ID of the customer who placed the order. The customer ID can be used with supported List and Search endpoints. For more information, see Customer ID integration points.

The Customers API provides two ways to return a list of customer profiles:

• ListCustomers returns an unfiltered list of customer profiles in sorted order.
• SearchCustomers returns a filtered list of customer profiles in sorted order.

By default, customer profiles are sorted alphanumerically by concatenating the given_name and family_name fields. If neither field is set, the following fields are compared in the following order:

• company_name
• email_address
• phone_number

The SearchCustomers endpoint allows you to search for customer profiles using the following filters:

• phone_number
• email_address
• creation_source
• created_at
• updated_at
• reference_id
• group_ids
• segment_ids
• custom_attribute

A search query can contain multiple query filters in any combination, which are combined as AND statements. For more information, see Search for Customer Profiles.

The Customers API provides the RetrieveCustomer and BulkRetrieveCustomers endpoints that you can use to retrieve one or more customer profiles by ID. The ID is stored in the id field in the corresponding Customer object.

When duplicate customer profiles are identified and merged, either manually by the seller or using automated detection, the existing profiles are merged into a single profile that is assigned a new ID.

If you specify the ID of a customer profile that was deleted in a merge operation, the Customers API returns the new customer profile. For example, suppose customers A and B are merged and a new customer C is created. If you call RetrieveCustomer using the ID of customer A or B, the Customers API returns customer C.

Instant profiles are customer profiles that are automatically created in a seller's Customer Directory following a payment. Future purchases made with the same card update the profile history with new payment details and other activities for your business.

When a payment is created without an explicit customer assignment, Square attempts to infer the associated customer. First, Square checks the customer_id field in the corresponding order. If this field isn't set, Square searches the Customer Directory for a matching profile using payment or related information (such as the billing and shipping address, email address, and payment source). If one cannot be found, Square attempts to create an instant profile. Note that this process is asynchronous and might take some time before customer_id is added to the payment.

If Square cannot find a matching customer profile and cannot create an instant profile, the customer_id field of the payment remains unset.

Customer objects that represent instant profiles have the creation_source field set to INSTANT_PROFILE. While instant profiles can be merged with other customer profiles in the Square Dashboard, merging doesn't retroactively link completed transactions to the newly created profile (that is, the customer_id field remains unchanged). To track merged customer profiles, subscribe to the customer.created webhook event.

Custom attributes can be used to extend the Customer data model by associating seller-specific or application-specific information with customer profiles. Custom attributes can store properties or metadata that help simplify integration, synchronization, and personalization workflows.

Working with custom attributes is different than working with native attributes that are accessed using the Customers API, such as given_name and email_address. For example, custom attributes aren't returned in a RetrieveCustomer or ListCustomers response or managed using CreateCustomer or UpdateCustomer. In addition, the custom attribute definition must be created in the Square seller account before the corresponding value can be assigned to custom profiles in the seller's Customer Directory.

To create and manage custom attribute definitions and custom attributes, use the Customer Custom Attributes API.

Customer profiles contain a version attribute that represents the current version of the customer profile. When a customer profile is created, the version is set to 0.

Square increments the version each time the profile is updated, except for changes to customer segment membership, cards on file, or features that are available only in Square products. For example, the version increments after changes to contact information, group membership, or email preferences but not after changes to the notes or custom fields managed in the Square Dashboard. The source of an update can be Square products, third-party applications, or an internal operation performed by Square.

You can use the version attribute to enable optimistic concurrency control. When you include version in an UpdateCustomer, BulkUpdateCustomers, or DeleteCustomer request, the operation fails if the current version of the customer profile is newer than the version specified in the request. For more information, see Optimistic Concurrency.

Square also uses the version to filter events that trigger webhook notifications. If concurrent updates are made to the same customer profile, Square compares the version numbers and sends a notification for the latest version only. Similarly, if you process notifications in batches, you can use the version attribute of the Customer object in the notification to determine the latest version of an updated customer profile.

Customers API endpoints don't support actions against previous versions of the customer profile.

Credit cards, debit cards, and gift cards can be associated with customer profiles. You can use the Cards API and Gift Cards API to save and manage cards on file for a customer. The customer_id field is used to map cards to a customer profile.

POS applications attempt to implicitly link cash tenders to existing customer profiles based on the provided receipt email or phone number. Implicit links to customer profiles show up in POS applications and the Square Dashboard.

The following migration notes apply to the Customers API.

The UpdateCustomer endpoint now supports sparse updates for the address field. With sparse updates, only fields that are added or changed are required in the request. In addition, removing the address field now requires the null update method. Earlier Square versions continue to require the complete address field for updates and accept an empty object ({}) to clear the field.

Starting in version: 2022-11-16

The following example requests are based on the Square version:

• Square version 2022-11-16 and later

  The following example request includes three address fields. These fields are updated if they are already defined or added if they aren't already defined.

  Update customer

  cURL

  The following example request updates the address.address_line_1 field and removes the address.address_line_2 field using the recommended null update method. For null update operations, the X-Clear-Null header must be present and set to true.

  curl https://connect.squareupsandbox.com/v2/customers/{CUSTOMER_ID} \
  -X PUT \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'X-Clear-Null: true' \
  -d '{
    "address": {
      "address_line_1": "505 Gardenia Lane",
      "address_line_2": null
    },
    "version": 1
  }'

  The following example request removes the address field from the customer profile. For null update operations, the X-Clear-Null header must be present and set to true.

  curl https://connect.squareupsandbox.com/v2/customers/{CUSTOMER_ID} \
  -X PUT \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'X-Clear-Null: true' \
  -d '{
    "address": null,
    "version": 2
  }'

  Note

  String-type fields can be cleared using the null update method (recommended) or by setting the value to an empty string.

  However, specifying "address": {} has no effect and doesn't clear the field.

• Square version 2022-10-19 and earlier

The following example request includes the complete address. This operation is an atomic update that replaces the entire address.

curl https://connect.squareupsandbox.com/v2/customers/{CUSTOMER_ID} \
-X PUT \
-H 'Square-Version: 2022-10-19' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{
  "address": {
    "address_line_1": "1313 Main St",
    "address_line_2": "Apt 2B",     
    "locality": "Springfield",
    "administrative_district_level_1": "MA",
    "postal_code": "01119"
  },
  "version": 0
}'

The following example request specifies an empty object to remove the address field from the customer profile:

curl https://connect.squareupsandbox.com/v2/customers/{CUSTOMER_ID} \
-X PUT \
-H 'Square-Version: 2022-10-19' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{
  "address": {},
  "version": 1
}'

CreateCustomer and UpdateCustomer requests that contain an invalid phone number now return a 400 INVALID_PHONE_NUMBER error. Valid phone numbers can optionally include a country code with the leading + sign and supported special characters. For more information, see Customer phone numbers. Earlier Square versions continue to accept any phone number that contains between 9–16 digits, even if they are invalid.

This change ensures that phone numbers added to the Customer Directory can be indexed for search operations. Existing phone numbers aren't affected.

Starting in version: 2022-10-19

Square performs additional validation on the phone number provided in the request. For invalid phone numbers, Square returns the 400 INVALID_PHONE_NUMBER error.

{
  "errors": [
    {
      "code": "INVALID_PHONE_NUMBER",
      "detail": "Expected phone_number to be a valid phone number",
      "field": "phone_number",
      "category": "INVALID_REQUEST_ERROR"
    }
  ]
}

For CreateCustomer and UpdateCustomer requests, the optional birthday value is now specified using a YYYY-MM-DD or MM-DD format. In addition, all birthday values in responses are now returned in YYYY-MM-DD format, including existing birthdays that were previously returned as timestamps. Earlier Square versions continue to accept YYYY-MM-DD or a timestamp (without time zone or time precision) in the request and return the timestamp in the response.

Starting in version: 2022-10-19

The following table shows example birthday values for a CreateCustomer or UpdateCustomer request:

The following table shows example birthday values for a Customer object in a response:

The following example responses for a request with an invalid birthday format are based on the Square version:

• Square version 2022-10-19 and later: 400 INVALID_TIME

  {
    "errors": [
      {
        "code": "INVALID_TIME",
        "detail": "Expected birthday to be a valid date formatted as `YYYY-MM-DD` or `MM-DD`.",
        "field": "birthday",
        "category": "INVALID_REQUEST_ERROR"
      }
    ]
  }

• Square version 2022-09-21 and earlier: 400 INVALID_VALUE

  {
    "errors": [
      {
        "code": "INVALID_VALUE",
        "detail": "This provided date `January 7` is not valid.",
        "field": "birthday",
        "category": "INVALID_REQUEST_ERROR"
      }
    ]
  }

All string-type fields in a CreateCustomer and UpdateCustomer request (except note) now have a maximum length constraint. Earlier Square versions enforce limits only for email_address (maximum 254 characters) and phone_number (maximum 16 digits).

Starting in version: 2022-10-19

The following table shows newly affected fields and the maximum number of characters allowed:

The following example responses for a request that exceeds the new maximum length limit are based on the Square version:

• Square version 2022-10-19 and later: 400 VALUE_TOO_LONG

  {
    "errors": [
      {
        "code": "VALUE_TOO_LONG",
        "detail": "Expected reference_id to contain a string of max length 100",
        "field": "reference_id",
        "category": "INVALID_REQUEST_ERROR"
      }
    ]
  }

• Square version 2022-09-21 and earlier: 200 OK

Starting in version: 2022-03-16

Calls to the CreateCustomer or SearchCustomers endpoint that contain an unrecognized field now return a BAD_REQUEST error. An unrecognized field is any field in the request body that isn't supported for the request. For earlier Square versions, the Customers API continues to ignore unrecognized fields.

The following are example responses based on the Square version:

• Square version 2022-03-16 and later: 400 BAD_REQUEST

  {
    "errors": [
      {
        "code": "BAD_REQUEST",
        "detail": "The field named '{field_name}' is unrecognized (line 4, character 9)",
        "field": "{field_name}",
        "category": "INVALID_REQUEST_ERROR"
      }
    ]
  }

• Square version 2022-02-16 and earlier: 200 OK (unrecognized fields are ignored)

Starting in version: 2022-03-16

Calls to the CreateCustomer or UpdateCustomer endpoint that specify an invalid phone number or email address return an INVALID_PHONE_NUMBER or INVALID_EMAIL_ADDRESS error code with a corresponding detail field. For earlier Square versions, the Customers API continues to return an INVALID_VALUE code.

The following are example responses based on the Square version:

• Square version 2022-03-16 and later

  • 400 INVALID_PHONE_NUMBER

    {
      "errors": [
        {
          "code": "INVALID_PHONE_NUMBER",
          "detail": "Expected phone_number to be a valid phone number",
          "field": "phone_number",
          "category": "INVALID_REQUEST_ERROR"
        }
      ]
    }

  • 400 INVALID_EMAIL_ADDRESS

    {
      "errors": [
        {
        "code": "INVALID_EMAIL_ADDRESS",
        "detail": "Expected email_address to be a valid email address",
        "field": "email_address",
        "category": "INVALID_REQUEST_ERROR"
        }
      ]
    }

• Square version 2022-02-16 and earlier

  • 400 INVALID_VALUE for phone_number

    {
      "errors": [
        {
          "code": "INVALID_VALUE",
          "detail": "Provided value for `phone_number` is invalid.",
          "field": "phone_number",
          "category": "INVALID_REQUEST_ERROR"
        }
      ]
    }

  • 400 INVALID_VALUE for email_address

    {
      "errors": [
        {
          "code": "INVALID_VALUE",
          "detail": "Provided value for `email_address` is invalid.",
          "field": "email_address",
          "category": "INVALID_REQUEST_ERROR"
        }
      ]
    }

Starting in version: 2021-10-20

Calls to the UpdateCustomer endpoint that don't specify any customer fields return a 400 BAD_REQUEST status code and error. For earlier Square versions, the Customers API continues to return a 200 OK status along with the customer profile.

The following are example responses based on the Square version:

• Square version 2021-10-20 and later: 400 BAD_REQUEST

  {
    "errors": [
      {
        "code": "BAD_REQUEST",
        "detail": "At least one field must be set to update a customer.",
        "category": "INVALID_REQUEST_ERROR"
      }
    ]
  }

• Square version 2021-09-15 and earlier: 200 OK

  {
    "customer": {
      "id": "62Y0FBFDQ0ZHDCGKBYP7FZK474",
      "created_at": "2020-11-12T03:51:06.371Z",
      "updated_at": "2021-08-29T00:03:37Z",
      "given_name": "Amelia",
      "family_name": "Earhart",
      "email_address": "[email protected]",
      ...
    }
  }

  Note

  In Square version 2021-09-15 and earlier, the updated_at timestamp is updated in response to this request. However, the version of the customer profile isn't updated.

Deprecated in version: 2021-06-16
Retired in version: TBD

The CreateCustomerCard endpoint is deprecated. You should use one of the following endpoints instead:

• To save a credit or debit card on file for a customer, call CreateCard in the Cards API and specify the customer_id field. This endpoint returns a Card object. For more information, see Create a Card on File and a Payment.

  Starting in Square version 2022-05-12, you can also call CreateTerminalAction to save a card on file when using the Terminal API. Specify the SAVE_CARD action type and save_card_options with the customer_id field. The card on file can then be managed using the Cards API. For more information, see Save a Card on File with the Terminal API.

• To save a gift card on file for a customer, call LinkCustomerToGiftCard in the Gift Cards API and specify the customer_id field. This endpoint returns a GiftCard object. For more information, see Manage gift cards on file.

Deprecated in version: 2021-06-16
Retired in version: TBD

The DeleteCustomerCard endpoint is deprecated. You should use one of the following endpoints instead:

• To disable a credit or debit card on file for a customer, call DisableCard in the Cards API. This endpoint returns a Card object. For more information, see Disable a card.
• To unlink a gift card on file from a customer, call UnlinkCustomerFromGiftCard in the Gift Cards API and specify the customer_id field. This endpoint returns a GiftCard object. For more information, see Manage gift cards on file.

Deprecated in version: 2021-06-16
Retired in version: 2025-01-23

The cards field on the Customer object is deprecated and will be retired at Square API version 2025-01-23. Use one of the following endpoints instead:

• To get the credit or debit cards on file for a customer, call ListCards in the Cards API and specify the customer_id query parameter. This endpoint returns a list of Card objects. For more information, see List cards saved for a customer.
• To get the gift cards on file for a customer, call ListGiftCards in the Gift Cards API and specify the customer_id query parameter. This endpoint returns a list of GiftCard objects. For more information, see Manage gift cards on file.

• Manage Customer Profiles
• Retrieve Customer Profiles
• Search for Customer Profiles
• Integrate Customer Profiles with Other Services
• Use Customer Webhooks
• Custom Attributes for Customers
• Video: Sandbox 101: Linking Customer Data