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:
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 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.
{
"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
}
}
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:
{
"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 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.