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 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.

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

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.

If the operation is successful, Square returns a 200 response with the new customer, as shown in the following example:

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.

Note

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:

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:

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:

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.

Note

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.

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
  • 1
  • 2
  • 3
  • 4
  • 5
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'

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 an empty object.

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

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.

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 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 fieldMaximum length
    address_line_1500
    address_line_2500
    address_line_3500
    administrative_district_level_1200
    administrative_district_level_2200
    administrative_district_level_3200
    locality300
    sublocality200
    sublocality_2200
    sublocality_3200
    postal_code12

    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.

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