Use the Square Customers API to perform CRUD operations on customers profiles in a Square account.
Customers API

Keep Customer Records

To keep records of customers for a Square seller, you create a customer profile and make timely updates when the customer contact 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.

Create a customer profile Permalink Get a link to this section

To create a customer profile, use the CreateCustomer endpoint. The customer profile is added to the seller's Customer Directory.

Before creating a customer profile, you need to collect 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.

In a web application, you can present these and other customer attributes as input text fields in a web form. 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.

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.

The following is an example CreateCustomer request:

Create Customer
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareupsandbox.com/v2/customers \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "company_name": "ACME Inc.",
    "email_address": "john.doe.jr@acme.com",
    "family_name": "Doe",
    "given_name": "John",
    "nickname": "Junior",
    "idempotency_key": "59973bb6-75ae-497a-a006-b2490example",
    "phone_number": "+1 (206) 222-3456"
  }'

When the customer profile is successfully created, you receive a 200 response similar to the following:

The creation_source attribute represents how the customer profile was created. This example is set to THIRD_PARTY because it was created by an application calling the API. Customer profiles that sellers create in the Square Seller Dashboard or Square Point of Sale application have a DIRECTORY creation source. If two profiles are merged, the resulting profile has a MERGED creation source. For the list of sources that create customer profiles, see CustomerCreationSource.

The version attribute is the current version of the customer profile. For more information, see Customer profile versions and optimistic concurrency support.

After a customer profile is created, you can retrieve it using the Customers API. For more information, see Retrieve Customer Profiles and Search for Customer Profiles.

Note

To create or manage custom attributes for customer profiles, use the Customer Custom Attributes API. For more information, see Custom Attributes for Customer Profiles.

Update a customer profile Permalink Get a link to this section

To update a customer profile, call the UpdateCustomer endpoint. To help ensure that you provide seamless experiences in customer interactions and communications, you should keep customer profiles up to date. You can update the following attributes: phone_number, email_address, address, birthday, company_name, family_name, given_name, nickname, note, and reference_id.

You must provide the customer ID when you call UpdateCustomer, as shown in the following example request. You can get the ID by calling ListCustomers or SearchCustomers.

The example request makes the following changes:

  • Sets the customer's birthday to January 13 (without the year) by specifying 0000-01-13.

  • Clears the customer's address by specifying an empty object.

  • Clears the customer's nickname by specifying an empty string.

Update Customer
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
curl https://connect.squareupsandbox.com/v2/customers/{customer_id} \
  -X PUT \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "birthday": "0000-01-13",
    "address": {},
    "nickname": "",
    "version": 0
  }'

The example request also includes the recommended version attribute, which must be set to the current version of the customer profile if included in the request. 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. Each time a customer profile is updated, the version is incremented. For more information, see Customer profile versions and optimistic concurrency support.

Note

To make any changes to an address, you must provide the complete Address object. Sparse updates are not supported for this object, so any fields that are undefined in the request are removed from the object.

You cannot use UpdateCustomer to change a card on file, change group membership, or update a custom attribute value.

Delete a customer profile Permalink Get a link to this section

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.

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.

Delete Customer
  • 1
  • 2
  • 3
  • 4
  • 5
curl https://connect.squareupsandbox.com/v2/customers/{customer_id}?version=2 \
  -X DELETE \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The example request also includes the recommended version attribute, which must be set to the current version of the customer profile if included in the request. 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.

Related topics Permalink Get a link to this section

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.