Manage Customer Profiles

Developers can use the Customers API to keep customer records for a Square seller by adding customer profiles to the seller's Customer Directory and making timely updates when customer information changes. Additionally, developers can delete customer profiles when a customer becomes inactive or requests to be removed.

Customer profiles can be created and managed individually or using bulk operations.

To add customer profiles to a seller's Customer Directory, call one of the following endpoints:

At least one of the following fields is required to create a customer profile. Your frontend application can collect this information from the customer using input fields.

  • given_name - The customer's first name.
  • family_name - The customer's last name.
  • company_name - The name of the customer's workplace.
  • email_address - The customer's email address.
  • phone_number - The customer's phone number.

Before creating a customer profile:

  • You must explicitly ask the customer for permission to store the information you collect. You should also be aware of other best practices for collecting information.
  • You should call the SearchCustomers endpoint and search by the customer's phone number, email address, or reference ID to avoid creating a duplicate customer profile.

To create a single customer profile, call CreateCustomer and provide the customer data. The following is an example request:

Create customer

Note

The BulkCreateCustomers endpoint can also be used to create a single customer.

If the operation is successful, Square returns a 200 status code and a customer field that contains the new customer profile, as shown in the following example.

To create 1 to 100 customer profiles in a bulk operation, call BulkCreateCustomers and provide a map of key-value pairs that represent individual create requests.

For each key-value pair, the key is an idempotency key and the value is the customer data used to create the customer profile:

{ "customers": { "idempotency_key_1": { // customer fields }, "idempotency_key_2": { // customer fields }, "idempotency_key_3": { // customer fields }, ... } }

The following BulkCreateCustomers request creates three customer profiles:

Bulk create customers

For bulk operations, Square processes the create requests individually and returns a map of responses.

If the BulkCreateCustomers operation is successfully processed, Square returns a 200 status code and a responses map of key-value pairs that represent the responses for individual create requests.

For each key-value pair, the key is an idempotency key that was specified in the request and the value is either the new customer profile (if the request succeeded) or error information (if the request failed). For example:

Note that the responses might not be returned in the same order as the individual create requests sent to BulkCreateCustomers.

Note

Idempotency keys are optional for CreateCustomer requests and required for BulkCreateCustomers requests. An idempotency key is a client-generated string (for example, a UUID) that Square uses to ensure a request is processed only once. An application cannot reuse idempotency keys in requests to the same seller.

Keeping customer profiles up to date helps to maintain seamless experiences in customer interactions and communications. To update customer profiles, call one of the following endpoints:

You can update the following fields:

To use optimistic concurrency control when updating customer data, include the version field and specify the current version of the customer profile. Note that setting this field to null has no effect.

To update a single customer profile, call UpdateCustomer and provide the customer ID and the fields you want to change. If needed, you can get the customer ID by calling SearchCustomers or ListCustomers.

The following UpdateCustomer request sets the customer's birthday to January 13 (without the year) and updates some address fields.

Update customer

Note

The BulkUpdateCustomers endpoint can also be used to update a single customer.

If the UpdateCustomer operation is successful, Square returns a 200 status code and a customer field that contains the updated customer profile, as shown in the following example:

To update 1 to 100 customer profiles in a bulk operation, call BulkUpdateCustomers and provide a map of key-value pairs that represent individual update requests.

For each key-value pair, the key is a customer ID and the value is the customer data used to update the customer profile. If needed, you can get the customer ID by calling SearchCustomers or ListCustomers.

{ "customers": { "customer_id_1": { // customer fields }, "customer_id_2": { // customer fields }, "customer_id_3": { // customer fields }, ... } }

The following BulkUpdateCustomers request updates two customer profiles:

Bulk update customers

For bulk operations, Square processes the update requests individually and returns a map of responses.

If the BulkUpdateCustomers operation is successfully processed, Square returns a 200 status code and a responses map of key-value pairs that represent the responses for individual update requests.

For each key-value pair, the key is a customer ID that was specified in the request and the value is either the updated customer profile (if the request succeeded) or error information (if the request failed). For example:

Note that the responses might not be returned in the same order as the individual update requests sent to BulkUpdateCustomers.

Update operations support using a sparse update object, which only needs to include fields that are added, changed, or cleared. You can clear fields using one of the following methods:

  • Set the value to null (recommended).
  • Set the value to an empty string. This method applies only to String-type fields.

The following example request updates the address.address_line_1 and birthday fields and clears the address.address_line_2 and nickname fields using the null update method:

Update customer

The following example request clears the address field and updates the phone_number field. To remove the address from the customer profile, you must use the null update method.

Update customer

Note

To use optimistic concurrency control when updating customer data, include the version field and specify the current version of the customer profile.

To delete customer profiles from the seller's Customer Directory, call one of the following endpoints:

A delete operation permanently removes the customer profile from the Customer Directory in the seller account across all locations. You might want to delete a customer profile when a customer is inactive for a specified period of time or when the customer makes an explicit request to be removed from the customer base.

To delete a single customer profile, call DeleteCustomer and provide the customer ID. If needed, you can get the customer ID by calling SearchCustomers or ListCustomers.

Delete customer

The example request also includes the recommended version attribute, which must be set to the current version of the customer profile when included in the request. For more information, see Considerations.

Note

The BulkDeleteCustomers endpoint can also be used to delete a single customer.

If the DeleteCustomer operation is successful, Square returns a 200 response with an empty object.

{}

To delete 1 to 100 customer profiles in a bulk operation, call BulkDeleteCustomers and provide the IDs of the customer profiles to delete. If needed, you can get the customer ID by calling SearchCustomers or ListCustomers.

The following BulkDeleteCustomers request deletes four customer profiles:

Bulk delete customers

Note that BulkDeleteCustomers operations don't support specifying a version field for customer profiles.

For bulk operations, Square processes the delete requests individually and returns a map of responses.

If the BulkDeleteCustomers operation is successfully processed, Square returns a 200 status code and a responses map of key-value pairs that represent the responses for individual delete requests.

For each key-value pair, the key is a customer ID that was specified in the request and the value is either an empty object (if the request succeeded) or error information (if the request failed). For example:

{ "responses": { "W8Q7NZQT08R6V6BSKVVC1VW5B0": {}, "P6BZGEMCPAP4P31Y9M8PWQWE80": {}, "8K35J21GQM4MVXDQTHCQBQDZ58": {}, "1PTNXQXT5J2KS2YF7R80GHP69Z": { "errors": [ { "code": "NOT_FOUND", "detail": "Customer with ID `1PTNXQXT5J2KS2YF7R80GHP69Z` not found.", "category": "INVALID_REQUEST_ERROR" } ] } } }

Note that the responses might not be returned in the same order as the list of customer IDs sent to BulkDeleteCustomers.

The following Square integration scenarios are affected when a customer profile is deleted:

  • Gift cards on file - Gift cards stored on file for the customer are unlinked when the customer profile is deleted. They can still be used to create a Square payment because a customer_id isn't required or validated for a gift card payment.

  • Loyalty accounts - The loyalty account associated with the customer is deleted, along with any remaining loyalty points. Loyalty events associated with the loyalty account aren't deleted; however, searching events using the ID of a deleted account isn't supported.

  • Subscription billing - All subscriptions associated with the customer are canceled.

  • Bookings - Bookings associated with the customer aren't canceled. Before deleting a customer profile, you should call ListBookings to find the bookings that are scheduled for the customer and then call CancelBooking for each booking.

  • Credit and debit cards on file - Credit and debit cards stored on file for the customer aren't disabled or deleted. However, they can no longer be used to create a Square card-on-file payment for the customer. Before deleting a customer profile, you should call ListCards using the customer_id query parameter to find any cards on file and then call DisableCard for each card. Filtering by customer_id after the profile is deleted isn't supported.

  • Automatic invoice payments - Invoices associated with the customer that are scheduled for automatic payment aren't canceled. Future automatic payments don't succeed, but Square continues to send invoice-related communications to the email address specified in the invoice_recipient.email_address field (which allows customers to make a payment from the invoice payment page). If needed, you can call SearchInvoices using the customer_ids query filter to list invoices for the customer and then call CancelInvoice.

  • Transaction history - Order and payment records aren't deleted. The SearchOrders endpoint can be used to search for orders using the ID of deleted customers.

    When customer profiles are deleted as a result of a merge operation, searching for orders using the ID of the new merged customer profile doesn't return orders whose customer_id is the IDs of the deleted customer profiles.

  • Custom attributes - Square deletes all custom attributes that are associated with the deleted customer profile.

Link to section

Considerations

You should be aware of the following considerations when managing customer profiles, which are represented by Customer objects:

  • Managing group membership - To change group membership, call AddGroupToCustomer or RemoveGroupFromCustomer. CreateCustomer or UpdateCustomer cannot be used to manage membership in a customer group.

  • Managing customer-related custom attributes - To work with custom attributes (also known as custom fields), use the Customer Custom Attributes API. CreateCustomer or UpdateCustomer cannot be used to add or update a custom attribute.

  • Managing cards on file - To manage stored credit and debit cards, use the Cards API. To manage stored gift cards, use the Gift Cards API. Using the Customers API to manage cards on file for the customer is deprecated. For more information, see Migration notes.

  • Merging customer profiles - Using the Customers API to merge customer profiles isn't supported.

  • Webhooks - Customer profiles in the Customer Directory are managed using Square products (such as the Seller Dashboard and Square Point of Sale) and through calls to Square APIs. Each create, update, or delete event triggers a separate webhook notification, even for bulk operations.

    You can subscribe to the following webhook events to be notified when customer profiles are added, changed, or removed:

    • customer.created
    • customer.updated
    • customer.deleted

    The customer.created event is useful for tracking customer profiles affected by a merge operation. For more information, see Use Customer Webhooks.

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

  • Sandbox Seller Dashboard - When testing the Customers API in the Square Sandbox, the customer profiles that you create can be viewed and managed from the Customer Directory in the Sandbox Seller Dashboard.

    To access the Sandbox Seller Dashboard for a test account, open the Sandbox test accounts page in the Developer Dashboard, and then choose Square Dashboard next to the test account. The default test account is created by Square and granted full access to the Sandbox resources in your account.

  • Creation source - The creation_source field is assigned by Square and represents how the customer profile was created. Customer profiles created by an application calling the Customers API are set to THIRD_PARTY. For customer profiles created by sellers in Square Point of Sale or the Seller Dashboard, the creation source is DIRECTORY. If a new customer profile is created by merging existing profiles, the creation source is MERGED. For the list of sources that create customer profiles, see CustomerCreationSource.

  • Customer versions - The version field represents the current version of the customer profile. The version is incremented each time a customer profile is updated.

    Square recommends including the version field in UpdateCustomer, BulkUpdateCustomers, and DeleteCustomer requests. Doing so allows the operation to succeed only if the current version of the customer profile matches the version specified in the request. Otherwise, the request fails with a CONFLICT error. For more information, see Customer profile versions and optimistic concurrency support.

    Note that BulkDeleteCustomers requests don't support specifying the version field.

  • Customer phone numbers - The phone number for a customer profile is stored in the phone_number field. If phone_number is provided in a CreateCustomer or UpdateCustomer request, the Customers API validates the value as follows:

    Character constraints:

    • The phone number must contain between 9 and 16 digits.
    • The phone number can contain spaces, a leading + symbol (when used with a country code), and the special characters (, ), -, and .. Alphabetical characters aren't allowed.

    Regional validation:

    • For national phone numbers where a country code isn't specified, the Customers API validates phone numbers based on the country of the seller. If a country isn't specified for the seller, US is used by default. The following are some validation examples:
      • The phone number must be valid for the seller's country. For example, 655560344 isn't a valid number for a US seller, because it's an ES number.
      • The area code must be valid for the seller's country. For example, 418184082 isn't a valid JP phone number for a JP seller because 41 isn't a valid area code in Japan.
      • The exchange code (or telephone prefix) must be valid for the seller's country. For example, 6091234567 isn't a valid US phone number for a US seller because an exchange code in the United States cannot start with a 1.
    • For international phone numbers where a country code is specified:
      • The country code must be valid and include the leading + symbol. A phone number that uses this format is considered E.164-compliant. E.164 is the international standard for formatting phone numbers.

    The national or international version of a phone number is valid for customers in the same country as the seller. For example, a US seller can store the following US phone numbers: 234.567.8901, +1 (234) 567-8901, and +12345678901. The international version of phone numbers must be used for customers in a different country. Square returns a 400 INVALID_PHONE_NUMBER error if the request contains an invalid phone number.

    Note

    The Customers API also accepts phone numbers that use an international prefix in front of the country code instead of the + symbol. A phone number can include the + or an international prefix, but not both.

    The international prefix changes according to the country of the seller. In contrast, E.164-compliant phone numbers are valid for any country (for example, a phone number that is valid for a US seller is also valid for a JP seller).

    For example, the Customers API accepts 011 1 4152345678 for a US seller and 010 1 4152345678 for a JP seller. Alternatively, both these numbers are valid for any country if provided as +14152345678 (without the international prefix).

  • Customer addresses - The physical address for a customer profile is stored in the address field, which is represented by an Address object. The following table shows the maximum number of characters the Customers API allows for string-type address fields:

    Address fieldMaximum length
    address_line_1500
    address_line_2500
    address_line_3500
    administrative_district_level_1200
    administrative_district_level_2200
    administrative_district_level_3200
    locality300
    sublocality200
    sublocality_2200
    sublocality_3200
    postal_code12

    The first_name and last_name address fields are ignored for customer profiles. For information about how address fields are used, see Working with Addresses.

  • Customer birthdays - The customer's birthday is stored in the birthday field. For a create or update request, birthday is specified using YYYY-MM-DD or MM-DD format and returned in YYYY-MM-DD format. If no year is specified in the request, 0000 is used as the year portion.

  • Updates to the Customer Directory - Customer profiles can be retrieved using the SearchCustomers, ListCustomers, RetrieveCustomer, and BulkRetrieveCustomers endpoints. For more information, see Retrieve Customer Profiles and Search for Customer Profiles.

    New and updated customer profiles are typically available in SearchCustomers and ListCustomers endpoints in less than 30 seconds, though some updates can take up to 1 minute to propagate. Occasionally, incidents, outages, and other network conditions can slow the propagation even further. Under such conditions, newly created or updated profiles might not be included in your search or list results. When this happens, wait a short time and then retry your request.

Link to section

See also