Customers API

Keep Customer Records

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.

Create a customer profile
Update a customer profile
Delete a customer profile
Considerations
Related topics

Link to section
Create a customer profile

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:

Create Customer

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

curl https://connect.squareupsandbox.com/v2/customers \
  -X POST \
  -H 'Square-Version: 2023-01-19' \
  -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",
    "phone_number": "+1 (206) 222-3456",
    "address": {
      "address_line_1": "1955 Broadway",
      "locality": "Springfield",
      "administrative_district_level_1": "MA",
      "postal_code": "01111"
    },
    "idempotency_key": "59973bb6-75ae-497a-a006-b2490example"
  }'

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

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

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.

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:

1
2
3
4
5
6
7
8
9
10

{
  "errors": [
    {
      "code": "BAD_REQUEST",
      "detail": "The field named '<name>' is unrecognized (line 2, character 3)",
      "field": "<name>",
      "category": "INVALID_REQUEST_ERROR"
    }
  ]
}

Link to section
Update a customer profile

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 and MM-DD formats are supported in the request. For this 01-13 example value, Square sets the birthday field to 0000-01-13.
Updates some fields in the customer's address.

Update Customer

1
2
3
4
5
6
7
8
9
10
11
12
13
14

curl https://connect.squareupsandbox.com/v2/customers/{{customer_id}} \
  -X PUT \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "birthday": "01-13",
    "address": {
      "address_line_1": "1313 Main St",
      "address_line_2": "Apt 2B",
      "postal_code": "01119"
    },
    "version": 0
  }'

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

{
  "customer": {
    "id": "FQWDXGBB2Q9WT1ZD6HKKSE9NQC",
    "created_at": "2022-05-29T21:14:49.48Z",
    "updated_at": "2022-09-16T09:36:22Z",
    "given_name": "John",
    "family_name": "Doe",
    "nickname": "Junior",
    "email_address": "john.doe.jr@acme.com",
    "address": {
      "address_line_1": "1313 Main St",
      "address_line_2": "Apt 2B",
      "locality": "Springfield",
      "administrative_district_level_1": "MA",
      "postal_code": "01119"
    },
    "phone_number": "+1 (206) 222-3456",
    "company_name": "ACME Inc.",
    "preferences": {
      "email_unsubscribed": false
    },
    "creation_source": "THIRD_PARTY",
    "birthday": "0000-01-13",
    "segment_ids": [
      "MLYQHTSHXM6E8.REACHABLE",
      "gv2:8ESCGMK9GN26570X8VR2AP9W1G"
    ],
    "version": 1
  }
}

If the operation fails, the errors field in the response contains any errors that occurred while processing the request. For example:

1
2
3
4
5
6
7
8
9
10

{
  "errors": [
    {
      "code": "INVALID_PHONE_NUMBER",
      "detail": "Expected phone_number to be a valid phone number",
      "field": "phone_number",
      "category": "INVALID_REQUEST_ERROR"
    }
  ]
}

Link to section
Clearing customer profile fields

The UpdateCustomer endpoint supports two methods for clearing fields:

Recommended. Set the value to null and include the X-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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

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
    },
    "nickname": null,
    "version": 1
  }'

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.

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-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'X-Clear-Null: true' \
  -d '{
    "address": null,
    "phone_number": "+1 (619) 555-7890",
    "version": 2
  }'

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.

Link to section
Delete a customer profile

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.

Delete Customer

curl https://connect.squareupsandbox.com/v2/customers/{{customer_id}}?version=2 \
  -X DELETE \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

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:

{
  "errors": [
    {
      "code": "NOT_FOUND",
      "detail": "Customer with ID `FQWDXGAB2Q9WT1ZD60KKSE9NQC` not found.",
      "category": "INVALID_REQUEST_ERROR"
    }
  ]
}

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 call CancelBooking 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 the customer_id query parameter to find any cards on file and then call DisableCard for each card. Filtering by customer_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 call SearchInvoices using the customer_ids query filter to list invoices for the customer and then call CancelInvoice.
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.

Link to section
Considerations

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 or UpdateCustomer 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 or UpdateCustomer 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. You can subscribe to the following webhook events to be notified when customer profiles are added, changed, or removed in the Customer Directory:
- 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 in UpdateCustomer and DeleteCustomer 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 a CONFLICT 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. If phone_number is provided in a CreateCustomer or UpdateCustomer 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 a US seller, because it is an ES number.
  - The area code must be valid for the seller's country. For example, 418184082 is not a valid JP phone number for a JP seller because 41 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 valid US phone number for a US 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 following US 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 a 400 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 a JP seller).
For example, the Customers API accepts 011 1 4152345678 for a US seller and 010 1 4152345678 for a JP 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-type address 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 and last_name fields have a maximum length of 300 characters, but these fields are ignored if they are present in a CreateCustomer or UpdateCustomer 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. For CreateCustomer or UpdateCustomer requests, birthday is specified using YYYY-MM-DD or MM-DD format and returned in YYYY-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 and ListCustomers 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.

Link to section
Related topics

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

Keep Customer Records

On this page

Link to section
Create a customer profile

Note

Note

Link to section
Update a customer profile

Link to section
Clearing customer profile fields

Note

Link to section
Delete a customer profile

Link to section
Considerations

Note

Link to section
Related topics

On this page

Keep Customer Records

On this page

Link to section Create a customer profile

Note

Note

Link to section Update a customer profile

Link to section Clearing customer profile fields

Note

Link to section Delete a customer profile

Link to section Considerations

Note

Link to section Related topics

On this page

Link to section
Create a customer profile

Link to section
Update a customer profile

Link to section
Clearing customer profile fields

Link to section
Delete a customer profile

Link to section
Considerations

Link to section
Related topics