Manage Customers and Integrate with Other Services

In the Square Customer Directory, customers are represented by customer profiles. A customer profile contains contact and personal information about a customer (such as name, email address, phone number, and birthday) and supplemental information (such as the groups or segments the customer belongs to). Customer profiles can be created using Square APIs and Square first-party products and experiences, such as the Square Seller Dashboard and Point of Sale applications.

Overview

You can use the Customers API to create and manage customer profiles for Square sellers, including membership in customer groups. The Customers API can also be used in combination with other Square APIs, Square first-party products, and third-party tools to provide robust experiences for sellers and their customers. For example, to make orders searchable by customer, you can link a customer ID to the orders that you create with the Orders API.

The following are examples of some of the activities you can perform using the Customers API:

• Keep customer records for a Square seller account.

• Synchronize customer data.

• Search for customers using supported query filters.

• Integrate customer data with other Square services to facilitate the customer purchasing experience.

Supported Customers API operations

You can use Customer API endpoints to perform the following operations:

Keep customer records

• CreateCustomer. Create a customer profile in a seller account.

• UpdateCustomer. Update a customer profile.

• DeleteCustomer. Delete a customer profile from a seller account.

  For more information, see Keep Customer Records.

Retrieve customer profiles

• RetrieveCustomer. Retrieve a customer using the customer ID.

• ListCustomers. List the customer profiles in a seller account.

  For more information, see Retrieve Customer Profiles.

Search for customer profiles

• SearchCustomers. Search for customer profiles in a seller account using one or more query filters.

  For more information, see Search for Customer Profiles.

Manage group membership

• AddGroupToCustomer. Assign a group membership to a customer profile.

• RemoveGroupFromCustomer. Remove a group membership from a customer profile.

  For more information, see Manage customer group membership.

Customer components

The Customers API works with the following primary data types:

• Customer. Represents a single customer profile and contains contact information such as name, address, email, and phone number. It can also have one or more associated cards on file.

• Address. A collection of strings representing a physical address.

• CustomerGroup. Represents a group of customer profiles created explicitly.

• CustomerSegment. Represents a group of customer profiles matching one or more predefined filter criteria.

• CustomerPreferences. Represents a customer's preference for receiving marketing emails and contains a single field that can have a true or false value.

A Customer object needs at least one of the following:

• 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 have a valid area code and 9 – 15 numbers. Square uses the libphonenumber library from Google to validate phone numbers.

Customer objects can also contain:

• An address.

• A note about the customer that the Customers API has read and write access to its text value. This is not the same as the rich Notes feature in the Square Seller Dashboard, which does not provide any API access.

• A reference ID to associate the customer with an entity in another system.

Customer objects can be associated with a collection of custom attributes that store properties and metadata that are not natively available on the object. For more information, see Custom attributes.

Sorting and searching customer profiles

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

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

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

Sorting

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

Searching

The SearchCustomers endpoint accepts one or more supported query filters to search for customer profiles. Supported query filters are based on the creation source, created date, updated date, customer group ID, reference ID, email address, and phone number.

When multiple filter criteria are provided, they are combined as an AND statement. For example, consider the following set of customer profiles, all of which were updated in the last week:

• Customer A. The profile was created 1 year ago through an eCommerce site using the Customers API.

• Customer B. The profile was created 2 months ago through an eCommerce site using the Customers API.

• Customer C. The profile was created 2 weeks ago through the Square Point of Sale application.

A customer query that includes the following restrictions only returns the Customer B profile, because it is the only profile that satisfies all three filters:

• Include customer profiles created through the Customers API.

• Include customer profiles created in the last 6 months.

• Include customer profiles updated in the last week.

A customer query that includes the following restrictions returns the Customer A and Customer B profiles:

• Include customer profiles created through the Customers API.

• Include customer profiles updated in the last week.

A customer query that only filters profiles based on the last update date returns all three customer profiles:

• Include customer profiles updated in the last week.

Retrieving a customer profile by ID

You can use the Customers API to retrieve a customer profile of a given customer_id.

When duplicate customer profiles are identified and merged, either manually or using automated detection, the existing profiles are merged into a single profile with a new customer_id. If you specify any of the old customer_id values to retrieve the customer profile, you receive the merged profile of the new customer_id.

For example, if customer profiles with customer_id_a (A) and customer_id_b (B) are merged, a new customer profile with customer_id_c (C) is created. If you call the Customers API to retrieve either the customer profile A or B, you get the customer profile C.

Instant profiles

Instant profiles are customer profiles that are automatically created following a payment. The creation_source attribute of the Customer resource for an instance profile is set to INSTANT_PROFILE.

If a customer's name is collected from a payment card and a matching profile does not already exist within your directory, Square creates an instant customer profile. Future purchases made with that card update the customer's profile with new payment details and other activity with your business.

While instant profiles can be merged with manually created customer profiles in the Square Seller Dashboard, merging does not retroactively link completed transactions to the newly created profile (the customer_id field is still empty).

Custom attributes

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 are not 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. For more information, see Custom Attributes for Customer Profiles.

Customer profile versions and optimistic concurrency support

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 first-party 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 Seller Dashboard. The source of an update can be first-party 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 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 do not support actions against previous versions of the customer profile.

Customer profiles and cards on file

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.

Customer profiles and cash transactions

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 Seller Dashboard.

Requirements and limitations

• 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 Overview.

• 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 endpoint does not check for duplicate records during profile creation. To avoid creating duplicate profiles, use the SearchCustomers endpoint to 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 does not 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 limitations. The Customers API cannot be used to associate customers with payments processed through the Checkout API.

  In addition, orders made from Square Online stores might not include a customer_id when retrieved from the Orders API, so you should not rely on this field for your integration.

• 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 does not currently return any orders made using a previous customer ID. For more information, see Customer assignments for orders and payments.

• No support for bulk imports. The Customers API does not currently support a bulk create operation or other method that can be used to import a batch of customers (for example, from an external database). You must call CreateCustomer to add customers individually. 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 rate limiting errors. For more information, see RATE_LIMIT_ERROR.

• 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:

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11

  {
    "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 or UpdateCustomer requests in other countries, Square returns a 400 BAD_REQUEST error for Square version 2021-10-20 or later. For earlier versions, Square ignores this field.

  • Square does not verify that the eu_vat identification number is a valid tax ID.

  • Square does not 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 does not support all customer profile attributes or all features that are available in the Seller Dashboard. For example:

  • Email or text messages. Sellers can send email or text messages directly to a customer from the Seller 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 Seller Dashboard are not included in the Customer object. However, the API does provide an optional note field that displays on the Personal Information card in the Seller Dashboard.

  • Private customer feedback. The private feedback that customers can provide from an emailed receipt is not 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.

• App Marketplace requirements. If you intend to list your application on the Square App Marketplace, see the related Customers API Requirements.

• 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 have not enabled payment processing on your account (or if you are not sure), visit squareup.com/activation.

Migration notes

The following migration notes apply to the Customers API.

CreateCustomer and SearchCustomers requests with unrecognized fields are rejected

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 is not 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

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10

  {
    "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)

CreateCustomer and UpdateCustomer requests with an invalid phone number or email address return specific error codes

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

    Copy

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10

    {
      "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

    Copy

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10

    {
      "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

    Copy

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10

    {
      "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

    Copy

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10

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

UpdateCustomer returns an error for empty requests

Starting in version: 2021-10-20

Calls to the UpdateCustomer endpoint that do not 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

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9

  {
    "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

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11

  {
    "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": "Amelia.Earhart@aviators.com",
      ...
    }
  }
  
  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 is not updated.

Deprecated CreateCustomerCard endpoint

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 DeleteCustomerCard endpoint

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 Customer.cards field

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

The cards field on the Customer object is deprecated. You should 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.

Related topics

• Keep Customer Records

• Retrieve Customer Profiles

• Search for Customer Profiles

• Integrate Customer Profiles with Other Services

• Use Customer Webhooks

• Custom Attributes for Customer Profiles

• Video: Sandbox 101: Linking Customer Data