Manage Customers and Integrate with Other Services
The Customers API lets you programmatically manage customer profiles in a Square account. This includes creating, looking up, updating, and removing a customer profile. As such, the API lets applications integrate relevant customer information with other services to provide seamless transaction experiences for sellers and their customers. For example, you can link a customer to an order to make the order searchable by the customer ID.
Product components
The Customers API works with the following primary data types:
Customer. Represents a single customer profile and contains contact information such as name, address, email, and phone number. It can also have one or more associated cards on file.
Address. A collection of strings representing a physical address.
CustomerGroup. Represents a group of customer profiles created explicitly.
CustomerSegment. Represents a group of customer profiles matching one or more predefined filter criteria.
CustomerPreferences. Represents a customer's preference for receiving marketing emails and contains a single field that can have a true or false value.
A Customer object needs at least one of the following:
A first or last name.
The name of the company where the customer works.
An email address, which must have the @ symbol and a valid domain.
A phone number, which must have a valid area code and 9 – 15 numbers. Square uses the libphonenumber library from Google to validate phone numbers.
Customer objects can also contain:
An address.
A note about the customer that the Customers API has read and write access to its text value. This is not the same as the rich
Notesfeature in the Square Seller Dashboard, which does not provide any API access.A reference ID to associate the customer with an entity in another system.
Note that 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 of the customer already exists.
Sorting and searching customer profiles
The Customers API provides two ways to return a list of customers:
ListCustomers returns an unfiltered list of customer profiles in sorted order.
SearchCustomers returns a filtered list of customer profiles in sorted order.
Sorting
By default, customer profiles are sorted alphanumerically by concatenating
the name fields. If neither name field is set, the following fields are compared
in order: company_name, email, and phone_number.
Searching
The SearchCustomers endpoint accepts one or more supported query filters to search for customer profiles. Supported query filters are based on the creation source, create date, update date, customer group ID, reference ID, email address, and phone number.
When multiple filter criterion are provided, they are combined
as an and statement. For example, consider the following set of customer
profiles, all of which were updated in the last week:
Customer A. The profile was created 1 year ago through an eCommerce site using the Customers API.
Customer B. The profile was created 2 months ago through an eCommerce site using the Customers API.
Customer C. The profile was created 2 weeks ago through the Square Point of Sale application.
A customer query that includes the following restrictions only returns the Customer B profile, because it is the only profile that satisfies all three filters:
Include customer profiles created through the Customers API.
Include customer profiles created in the last 6 months.
Include customer profiles updated in the last week.
A customer query that includes the following restrictions returns the Customer A and Customer B profiles:
Include customer profiles created through the Customers API.
Include customer profiles updated in the last week.
A customer query that only filters profiles based on the last update date returns all three customer profiles:
Include customer profiles updated in the last week.
Retrieving a customer profile by ID
You can use the Customers API to retrieve a customer profile of a given customer_id.
When duplicate customer profiles are identified and merged, either manually or by way of automated detection, the existing profiles are merged into a single profile with a new customer_id. If you specify any of the old customer_id values to retrieve the customer profile, you receive the merged profile of the new customer_id.
For example, if customer profiles with customer_id_a (A) and customer_id_b (B) are merged, a new customer profile with customer_id_c (C) is created. If you call the Customers API to retrieve either customer profile A or B, you get customer profile C.
Instant profiles
Instant profiles are customer profiles that are automatically created
following a payment. The creation_source attribute of the Customer resource for an instance profile is set to INSTANT_PROFILE.
If a customer's name is collected from a payment card and a matching profile does not already exist within your directory, Square creates an instant customer profile. Future purchases made with that card update the customer's profile with new payment details and other activity with your business.
While instant profiles can be merged with manually created customer profiles in the Square Seller Dashboard, merging does not retroactively link completed transactions to the newly created profile (the customer_id field is still empty).
Customer profile versions and optimistic concurrency support
Customer profiles contain a version attribute that represents the current version of the customer profile. When a customer profile is created, the version is set to 0.
Square increments the version each time the profile is updated, except for changes to customer segment membership, cards on file, or features that are available only in first-party applications. For example, the version increments after changes to contact information, group membership, or email preferences but not after changes to the notes or custom fields managed in the Seller Dashboard. The source of an update can be first-party applications, third-party applications, or an internal operation performed by Square.
You can use the version attribute to enable optimistic concurrency control. When you include version in an UpdateCustomer or DeleteCustomer request, the operation fails if the current version of the customer profile is newer than the version specified in the request. For more information, see Optimistic Concurrency.
Square also uses the version to filter events that trigger webhook notifications.
If concurrent updates are made to the same customer profile, Square compares the version numbers and sends a notification for the latest version only. Similarly, if you process notifications in batches, you can use the version attribute of the customer object in the notification to determine the latest version of an updated customer profile.
Customers API endpoints do not support actions against previous versions of the customer profile.
Customer profiles and cards on file
Credit cards, debit cards, and gift cards can be associated with customer profiles. You can use the Cards API
and Gift Cards API
(beta) to save and manage cards on file for a customer. The customer_id field is used to map cards to a customer profile.
Note
The CreateCustomerCard endpoint, DeleteCustomerCard endpoint, and Customer.cards field are deprecated. For more information, see Migrate to the Cards API and Gift Cards API.
Customer profiles and cash transactions
POS applications attempt to implicitly link cash tenders to existing customer profiles based on the provided receipt email or phone number. Implicit links to customer profiles show up in POS applications and the Seller Dashboard.
Requirements and limitations
Applications that use OAuth must have appropriate
CUSTOMER_READorCUSTOMER_WRITEaccess permissions to manage customer profiles. For more information, see Permissions Reference for the Customers API.
You must obtain permission from customers before you store their information. You must protect personally identifiable information (PII) and other sensitive information, such as customer name, address, and phone number. For more information, see Best Practices for Collecting Information.
The CreateCustomer endpoint does not check for duplicate records during profile creation. To avoid creating duplicate profiles, use the
SearchCustomersendpoint to search by phone number, email address, or reference ID to determine whether a profile of the customer already exists. For more information, see Search for Customer Profiles.
The SearchCustomers endpoint does not support searching by name, location, or the employee who created the customer profile. For information about supported search query filters, such as email address and phone number, see Search for Customer Profiles.
The Customers API cannot be used to link customers to payments processed through the Checkout API.
The Customers API does not currently support a bulk create operation or other method that can be used to import a batch of customers (for example, from an external database). You must call CreateCustomer to add customers individually. If your application sends a high number of calls to Square APIs in a short period of time, you should make sure to handle potential rate limiting errors. For more information, see My call returns a RATE_LIMITED error code.
The Customers API does not support all customer profile attributes or all features that are available in the Seller Dashboard. For example:
Email or text messages. Sellers can send email or text messages directly to a customer from the Seller Dashboard (in the production environment only). The Customers API cannot be used to send email or text messages.
Notes with reminders. The rich notes that sellers can create in the Seller Dashboard are not included in the
Customerobject. However, the API does provide an optional note field that displays on the Personal Information card in the Seller Dashboard.Private customer feedback. The private feedback that customers can provide from an emailed receipt is not included in the
Customerobject. For more information about this feature, see Private customer feedback you can work with.Marketing campaign email preferences. The
email_unsubscribedpreference indicates whether the customer has unsubscribed from marketing campaign emails. A value oftruemeans that the customer has opted out of email marketing from the current Square seller or from all Square sellers. This value is read-only from the Customers API. For information about how customers can set their preferences, see How Customers Can Unsubscribe From Square Marketing Emails.