Manage Customer Profiles

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:

If the operation is successful, Square returns a 200 response with the new customer, 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
  }
}

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.

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

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

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.

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:

{
  "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": "[email protected]",
    "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:

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

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:

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.

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

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.

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:

{
  "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 isn't 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 aren't deleted; however, searching events using the ID of a deleted account isn't supported.

• Subscription billing - All subscriptions associated with the customer are canceled.

• Bookings - Bookings associated with the customer aren't 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 aren't 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 isn't supported.

• Automatic invoice payments - Invoices associated with the customer that are scheduled for automatic payment aren't canceled. Future automatic payments don't 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 aren't 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 doesn't 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 isn't supported.

• Webhooks - Customer profiles in the Customer Directory are managed using Square products (such as the Seller Dashboard and Square Point of Sale) and through calls to Square APIs. You can subscribe to the following webhook events to be notified when customer profiles are added, changed, or removed:

  • 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 aren't allowed.

  Regional validation:

  • For national phone numbers where a country code isn't specified, the Customers API validates phone numbers based on the country of the seller. If a country isn't 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 isn't a valid number for a US seller, because it's an ES number.
    • The area code must be valid for the seller's country. For example, 418184082 isn't a valid JP phone number for a JP seller because 41 isn't a valid area code in Japan.
    • The exchange code (or telephone prefix) must be valid for the seller's country. For example, 6091234567 isn't 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.

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

• Retrieve Customer Profiles
• Search for Customer Profiles
• Custom Attributes for Customers