Applies to: Customers API
Learn how to create, update, and delete customer profiles in a Square seller account.
Developers can use the Customers API to keep customer records for a Square seller by adding customer profiles
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 profileCreates a single customer profile .BulkCreateCustomers
- Creates multiple customer profilesCreates 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.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
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.
To create a single customer profile, call CreateCustomer
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": "john.doe.jr@acme.com", "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
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": "sara.vera0101@gmail.com", "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": "antonio1568silva@gmail.com", "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 keysCreateCustomer
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.