The Square Customer Directory is a customer relationship management (CRM) tool that enables Square sellers to store customer information, analyze customer interactions and activity, and more. Customers are represented by customer profiles that contain 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 using Square APIs and Square products and experiences, such as the Seller Dashboard and Square Point of Sale.
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 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 channels such as analytics, marketing, loyalty, and personalization.
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 with the Customer Directory by using webhooks and polling for changes.
- Search for customers using supported query filters.
- Integrate customer data with other Square services to facilitate the customer purchasing experience.
Note
Applications typically collect customer information from their frontend client and call the Customers API from their backend server (for example, see Basic process flow). The developer must create the UI that collects customer information. Square doesn't provide a prebuilt form for this purpose.
You can use Customer API endpoints to perform the following operations to create and manage customer profiles in a seller account.
The following endpoints are used to manage 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:
Important
If you save customer contact information, you must obtain explicit permission from the customer. This means you should enable an option for the customer to agree explicitly to have their contact information stored on file. Storing customer contact information without explicit consent and any other form of abuse of customer information might result in your application being disabled without notice.
The Customers API works with the following primary data types:
- Customer - Represents a single customer profile and contains contact and other personal information such as name, address, email, and phone number.
- 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 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 that the Customers API has read and write access to its text value. This isn't the same as the rich
Notes
feature in the Seller Dashboard, which doesn't provide any API access. - A reference ID to associate the customer with an entity in another system.
- A list of customer groups and a list of customer segments to which the customer belongs.
Customer
objects can be associated with a collection of custom attributes that store properties and metadata that aren't natively available on the object. For more information, see Custom attributes.
Note
You should avoid creating duplicate customer profiles. Before you create a new profile, call the SearchCustomers endpoint and search by phone number, email address, or reference ID to make sure a profile doesn't already exist for the customer.
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.
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.
Retrieving a customer profile by ID
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.
If a customer isn't assigned to a payment, 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.
Note
Some regions prevent the creation of instant profiles or allow sellers to disable this feature.
If the customer_id
isn't set for a payment made using a non-payment-card payment method (such as gift card, ACH, or Cash App), Square doesn't attempt to find or create a customer profile to populate the customer_id
field.
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 Seller 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. For more information, see Custom Attributes for Customers.
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 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 Seller 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.
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.
The following migration notes apply to the Customers API.
Sparse updates and null updates for the address field in UpdateCustomer requests
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.
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 UpdateCustomers requests with invalid phone numbers are rejected
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"
}
]
}
Note
Starting in version 2022-10-19, the 400 INVALID_PHONE_NUMBER
error is always returned in the initial response. In earlier versions, the phone number is validated only after all other errors in the request have been resolved.
Birthday uses YYYY-MM-DD or MM-DD format
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
Example birthday formats in requests
The following table shows example birthday
values for a CreateCustomer
or UpdateCustomer
request:
Request | Square version 2022-10-19 and later | Square version 2022-09-21 and earlier |
---|
Birth year specified:
CreateCustomer or UpdateCustomer | 2001-04-20 | 2001-04-20 or
2001-04-20T00:00:00-00:00 |
Birth year not specified:
CreateCustomer or UpdateCustomer | 0000-04-20 or
04-20 | 0000-04-20 or
0000-04-20T00:00:00-00:00 |
Example birthday formats in responses
The following table shows example birthday
values for a Customer
object in a response:
Response | Square version 2022-10-19 and later | Square version 2022-09-21 and earlier |
---|
Birth year specified:
CreateCustomer ,
UpdateCustomer ,
RetrieveCustomer , ListCustomers , or
SearchCustomers | 2001-04-20 | 2001-04-20T00:00:00-00:00 |
Birth year not specified:
CreateCustomer ,
UpdateCustomer ,
RetrieveCustomer , ListCustomers , or
SearchCustomers | 0000-04-20 | 0000-04-20T00:00:00-00:00 |
The following example responses for a request with an invalid birthday format are based on the Square version:
Maximum length for string fields in CreateCustomer and UpdateCustomer requests
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:
Field | Maximum length |
---|
given_name | 300 |
family_name | 300 |
company_name | 500 |
nickname | 100 |
reference_id | 100 |
address.first_name | 300 |
address.last_name | 300 |
address.address_line_1 | 500 |
address.address_line_2 | 500 |
address.address_line_3 | 500 |
address.administrative_district_level_1 | 200 |
address.administrative_district_level_2 | 200 |
address.administrative_district_level_3 | 200 |
address.locality | 300 |
address.sublocality | 200 |
address.sublocality_2 | 200 |
address.sublocality_3 | 200 |
address.postal_code | 12 |
The following example responses for a request that exceeds the new maximum length limit are based on the Square version:
Note
Starting in version 2022-10-19, Square returns a VALUE_TOO_LONG
error if the email_address
limit is exceeded (instead of the INVALID_EMAIL_ADDRESS
and INVALID_VALUE
errors returned in earlier versions).
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 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:
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:
UpdateCustomer returns an error for empty requests
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:
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:
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:
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.