Manage Customer Profiles

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

Learn how to create, update, and delete customer profiles in a Square seller account.

Overview

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.

Link to section

Create customer profiles

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

CreateCustomer - Creates a single customer profile.
BulkCreateCustomers - Creates multiple customer profiles.

At least one of the following fields is required to create a customer profile. Your application frontend 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:

Get consent to store customer data - 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.
Check for duplicate profiles - 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.

Including a unique email_address, phone_number, or reference_id when creating a customer profile can make it easier to find customers later. Note that some Square API integrations might require email_address, phone_number, or other specific customer fields.

Link to section

Create a single 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 object that represents the new customer profile, as shown in the following example.

{
  "customer": {
    "id": "FQWDXGBB2Q9WT1ZD6HKKSE9NQC",
    "created_at": "2022-05-29T21:14:49.48Z",
    "updated_at": "2022-05-29T21:14:49Z",
    "given_name": "John",
    "family_name": "Doe",
    "nickname": "Junior",
    "email_address": "[email protected]",
    "address": {
      "address_line_1": "1955 Broadway",
      "locality": "Springfield",
      "administrative_district_level_1": "MA",
      "postal_code": "01111"
    },
    "phone_number": "+1 (206) 222-3456",
    "company_name": "ACME Inc.",
    "preferences": {
      "email_unsubscribed": false
    },
    "creation_source": "THIRD_PARTY",
    "version": 0
  }
}

Link to section

Create multiple customer profiles

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 attempts to create 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 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.
Error information if the request failed.

In the following example, two requests succeeded and one failed:

{
  "responses": {
    "452ea896-f36e-4c5c-95d5-e5aa727b9b2c": {
      "customer": {
        "id": "TFVGJNH46AVMDCZY93KKKF5QW4",
        "created_at": "2024-01-20T00:32:34.43Z",
        "updated_at": "2024-01-20T00:32:34Z",
        "given_name": "Vera",
        "family_name": "Sara",
        "email_address": "[email protected]",
        "phone_number": "+14167779999",
        "preferences": {
          "email_unsubscribed": false
        },
        "creation_source": "THIRD_PARTY",
        "version": 0
      }
    },
    "cbde1ec6-96df-40d4-8019-af9a4fa893ed": {
      "customer": {
        "id": "6ZK40WV46EM8M2AVC9ZEF7B018",
        "created_at": "2024-01-20T00:32:34.533Z",
        "updated_at": "2024-01-20T00:32:34Z",
        "given_name": "Silva",
        "family_name": "Antonio",
        "email_address": "[email protected]",
        "address": {
          "address_line_1": "1001 Broadway Ave",
          "address_line_2": "Apt 1311",
          "locality": "Toronto",
          "administrative_district_level_1": "ON",
          "country": "CA"
        },
        "phone_number": "+14375552222",
        "note": "Birthday Club member",
        "preferences": {
          "email_unsubscribed": false
        },
        "creation_source": "THIRD_PARTY",
        "birthday": "0000-07-22",
        "version": 0
      }
    },
    "716cefbc-3d71-4d7c-bdc8-9c7f84c2d793": {
      "errors": [
        {
          "code": "INVALID_EMAIL_ADDRESS",
          "detail": "Expected email_address to be a valid email address",
          "field": "email_address",
          "category": "INVALID_REQUEST_ERROR"
        }
      ]
    }
  }
}

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 but 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.

Link to section

Update customer profiles

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:

UpdateCustomer - Updates a single customer profile.
BulkUpdateCustomers - Updates multiple customer profiles.

You can add, edit, or remove the following fields:

given_name, family_name, company_name, and nickname
phone_number
email_address
address and address fields
reference_id
birthday
note
tax_ids (in supported countries only)

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

Link to section

Update a single customer profile

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:

{
  "customer": {
    "id": "FQWDXGBB2Q9WT1ZD6HKKSE9NQC",
    "created_at": "2022-05-29T21:14:49.48Z",
    "updated_at": "2022-09-16T09:36:22Z",
    "given_name": "John",
    "family_name": "Doe",
    "nickname": "Junior",
    "email_address": "[email protected]",
    "address": {
      "address_line_1": "1313 Main St",
      "address_line_2": "Apt 2B",
      "locality": "Springfield",
      "administrative_district_level_1": "MA",
      "postal_code": "01119"
    },
    "phone_number": "+1 (206) 222-3456",
    "company_name": "ACME Inc.",
    "preferences": {
      "email_unsubscribed": false
    },
    "creation_source": "THIRD_PARTY",
    "birthday": "0000-01-13",
    "segment_ids": [
      "MLYQHTSHXM6E8.REACHABLE",
      "gv2:8ESCGMK9GN26570X8VR2AP9W1G"
    ],
    "version": 1
  }
}

Link to section

Update multiple customer profiles

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 attempts to update 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 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.
Error information if the request failed.

In the following example, one request succeeded and one failed:

{
  "responses": {
    "6ZK40WV46EM8M2AVC9ZEF7B018": {
      "customer": {
        "id": "6ZK40WV46EM8M2AVC9ZEF7B018",
        "created_at": "2024-01-20T00:32:34.533Z",
        "updated_at": "2024-01-20T00:32:34Z",
        "given_name": "Silva",
        "family_name": "Antonio",
        "email_address": "[email protected]",
        "address": {
          "address_line_1": "900 1st Ave",
          "locality": "Toronto",
          "administrative_district_level_1": "ON",
          "country": "CA"
        },
        "phone_number": "+14375552222",
        "note": "Birthday Club member",
        "company_name": "Swatch Design",
        "preferences": {
          "email_unsubscribed": false
        },
        "creation_source": "THIRD_PARTY",
        "birthday": "0000-07-22",
        "version": 2
      }
    },
    "TFVGJNH46AVMDCZY93KKKF5QW4": {
      "errors": [
        {
          "code": "INVALID_EMAIL_ADDRESS",
          "detail": "Expected email_address to be a valid email address",
          "field": "email_address",
          "category": "INVALID_REQUEST_ERROR"
        }
      ]
    }
  }
}

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

Link to section

Sparse updates and clearing fields

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

Link to section

Delete customer profiles

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

DeleteCustomer - Deletes a single customer profile.
BulkDeleteCustomers - Deletes multiple customer profiles.

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.

Link to section

Delete a single customer profile

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.

{}

Link to section

Delete multiple customer profiles

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

Link to section

How deleting customer profiles affects other Square APIs and objects

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 Square 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.
Subscribe to the following webhook events to be notified when customer profiles are added, changed, or removed:
- customer.created - This event is also useful for tracking customer profiles affected by a merge operation.
- customer.updated
- customer.deleted
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_LIMIT errors.
Sandbox Square 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 Square Dashboard.
To access the Sandbox Square Dashboard for a test account, open the Sandbox test accounts page in the Developer Console, 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 Square-assigned creation_source field indicates how the customer profile was created, as shown in the following examples. For a complete list of sources, see CustomerCreationSource.
- THIRD_PARTY - Created by applications calling the Customers API.
- DIRECTORY - Created by sellers in the Square Dashboard or Square Point of Sale.
- MERGED - Created by merging two or more existing profiles.

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 as a string 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 field	Maximum length
`address_line_1`	500
`address_line_2`	500
`address_line_3`	500
`administrative_district_level_1`	200
`administrative_district_level_2`	200
`administrative_district_level_3`	200
`locality`	300
`sublocality`	200
`sublocality_2`	200
`sublocality_3`	200
`postal_code`	12

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

Docs

Manage Customer Profiles

On this page

Overview

Create customer profiles

Create a single customer profile

Note

Create multiple customer profiles

Note

Update customer profiles

Update a single customer profile

Note

Update multiple customer profiles

Sparse updates and clearing fields

Delete customer profiles

Delete a single customer profile

Note

Delete multiple customer profiles

How deleting customer profiles affects other Square APIs and objects

Considerations

Note

See also

On this page