Manage Customer Profiles
To keep records of customers for a Square seller, you create customer profiles and make timely updates when the customer information changes. You can also delete a profile if the customer is considered inactive or wants to be removed from the seller's Customer Directory.
To create a customer profile, call the CreateCustomer endpoint. The customer profile is added to the seller's Customer Directory.
Creating a customer profile requires at least one of the following customer attributes:
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.
To collect this information from the customer, your frontend application can present these and other customer attributes as input fields. Before creating a customer profile, make sure to explicitly ask the customer for permission to store the information you collect. For more information, see Best Practices for Collecting Information.
The following is an example CreateCustomer
request:
Note
The CreateCustomer
endpoint permits creating duplicate customer profiles. Before creating a new customer profile, you should call the SearchCustomers endpoint to search by phone number, email address, or reference ID to determine whether a profile for the customer already exists.
If the operation is successful, Square returns a 200
response with the new customer, as shown in the following example:
The creation_source
field added by Square 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.
After a customer profile is created, it can be retrieved using the RetrieveCustomer
, ListCustomers
, and SearchCustomers
endpoints. For more information, see Retrieve Customer Profiles and Search for Customer Profiles.
Note
Sellers create and manage customer profiles in the Customer Directory. While testing in the Sandbox, the customer profiles that you create using the Customers API can be accessed in the Sandbox Seller Dashboard. For more information, see Considerations.
If the operation fails, the errors
field in the response contains any errors that occurred while processing the request. For example:
To update a customer profile, call the UpdateCustomer endpoint. You should keep customer profiles up to date to help ensure that you provide seamless experiences in customer interactions and communications. You can update the following attributes: phone_number
, email_address
, address
, birthday
, company_name
, family_name
, given_name
, nickname
, note
, reference_id
, and tax_ids
(in supported countries
only).
You must provide the customer ID when you call UpdateCustomer
, as shown in the following example request. If needed, you can get the ID by calling ListCustomers or SearchCustomers. The UpdateCustomer
endpoint supports using a sparse update
object, which only needs to include fields that are added or changed.
The example request makes the following changes:
Sets the customer's birthday to January 13 (without the year). Both
YYYY-MM-DD
andMM-DD
formats are supported in the request. For this01-13
example value, Square sets thebirthday
field to0000-01-13
.Updates some fields in the customer's address.
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.
If the operation is successful, Square returns a 200
response with the updated customer, as shown in the following example:
If the operation fails, the errors
field in the response contains any errors that occurred while processing the request. For example:
The UpdateCustomer
endpoint supports two methods for clearing fields:
Recommended. Set the value to
null
and include theX-Clear-Null
header in the request. If the header is omitted,null
settings are ignored. For more information, see Clear a field value.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
field and clears the address.address_line_2
and nickname
fields using the null update method:
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.
Note
In Square versions 2022-10-19 and earlier:
Updating an address requires sending the complete address.
The
address
field can only be cleared by setting the value to an empty object ("address": {}
). In Square versions 2022-11-16 and later, Square ignores this setting and does not clear the field.
To delete a customer profile from the seller's Customer Directory, call the DeleteCustomer endpoint. 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.
A DeleteCustomer
operation permanently removes a customer profile from the Customer Directory in the seller account across all locations.
You must provide the customer ID when you call DeleteCustomer
, as shown in the following example request. You can get the ID by calling ListCustomers or SearchCustomers.
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.
If the operation is successful, Square returns a 200
response with an empty object.
If the operation fails, the errors
field in the response contains any errors that occurred while processing the request. For example:
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
is not 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 are not deleted; however, searching events using the ID of a deleted account is not supported.
Subscription billing. All subscriptions associated with the customer are canceled.
Bookings. Bookings associated with the customer are not canceled. Before deleting a customer profile, you should call
ListBookings
to find the bookings that are scheduled for the customer and then callCancelBooking
for each booking.Credit and debit cards on file. Credit and debit cards stored on file for the customer are not 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 thecustomer_id
query parameter to find any cards on file and then callDisableCard
for each card. Filtering bycustomer_id
after the profile is deleted is not supported.Automatic invoice payments. Invoices associated with the customer that are scheduled for automatic payment are not canceled. Future automatic payments do not 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 callSearchInvoices
using thecustomer_ids
query filter to list invoices for the customer and then callCancelInvoice
.Transaction history. Order and payment records are not 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 does not 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.
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
orUpdateCustomer
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
orUpdateCustomer
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 is not 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. 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.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 Developer Dashboard and choose Open next to the test account. The default test account is created by Square and granted full access to the Sandbox resources in your account.
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 inUpdateCustomer
andDeleteCustomer
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 aCONFLICT
error. For more information, see Customer profile versions and optimistic concurrency support.
Customer phone numbers. The phone number for a customer profile is stored in the
phone_number
field. Ifphone_number
is provided in aCreateCustomer
orUpdateCustomer
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 are not allowed.
Regional validation:
For national phone numbers where a country code is not specified, the Customers API validates phone numbers based on the country of the seller. If a country is not 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
is not a valid number for aUS
seller, because it is anES
number.The area code must be valid for the seller's country. For example,
418184082
is not a validJP
phone number for aJP
seller because41
is not a valid area code in Japan.The exchange code (or telephone prefix) must be valid for the seller's country. For example,
6091234567
is not a validUS
phone number for aUS
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 followingUS
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 a400 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 aJP
seller).For example, the Customers API accepts
011 1 4152345678
for aUS
seller and010 1 4152345678
for aJP
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-typeaddress
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
andlast_name
fields have a maximum length of 300 characters, but these fields are ignored if they are present in aCreateCustomer
orUpdateCustomer
request. For information about how address fields are used, see Working with Addresses.Customer birthdays. The customer's birthday is stored in the
birthday
field. ForCreateCustomer
orUpdateCustomer
requests,birthday
is specified usingYYYY-MM-DD
orMM-DD
format and returned inYYYY-MM-DD
format. If no year is specified in the request,0000
is used as the year portion.Updates to the Customer Directory. New and updated customer profiles are typically available in
SearchCustomers
andListCustomers
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.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.