What It Does

The Customers API makes it easy to seamlessly integrate customer information with the rest of the Square APIs. The Customers API can create and manage customer profiles and save credit card information (card on file) for future and recurring payments.

Requirements and limitations

• Email receipts ask customers whether their experience was positive or negative. Customer objects returned by the API do not include this customer experience data on payments.

• The Customers API cannot be used to send customers emails.

• The Customers API does not check for duplicate records during profile creation.

• The Customers API cannot link customers to payments processed through the Checkout API.

• The Customers API cannot filter customer records by location or the employee who created the record.

• Filtering for customer searches is currently limited to creation source and timestamps for creation and last update.

Product components

The Customer API works with the following primary data types:

• Customer — Represents a single customer 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.

• CustomerGroupInfo — Contains information about a customer group and a unique ID.

• CustomerPreferences — Represents a customer's preference for receiving marketing emails. 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. Email addresses must have the @ symbol and a valid domain.

• A phone number. Phone numbers 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.

• A reference ID to associate the customer with an entity in another system.

Note that the CreateCustomer endpoint does not prevent creating duplicate customer records. We recommend writing code that identifies and deletes duplicate customer records using the DeleteCustomer endpoint or using the ListCustomers endpoint to check for duplicates before saving a Customer record.

Sorting and searching customer profiles

The Customers API provides 2 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 files. If neither name field is set, the following fields are compared in order: company_name, email, phone_number.

Searching

The SearchCustomer endpoint also accepts a profile query built on a Customer filter. Filters restrict the result set based on creation source, create date, and update date.

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 — their profile was created 1 year ago through an eCommerce site using the Customers API.

• Customer B — their profile was created 2 months ago through an eCommerce site using the Customers API.

• Customer C — their profile was created 2 weeks ago through the Square Point of Sale app.

A Customer query that includes the following restrictions:

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

will only return the "Customer B" profile, because it is the only one that satisfies all 3 filters.

A customer query that includes the following restrictions:

• Include customer profiles created through the Customers API.

• Include customer profiles updated in the last week.

will return the "Customer A" and "Customer B" profiles.

And a customer query that only filters profiles based on the last update date:

• Include customer profiles updated in the last week.

will return all 3 Customer profiles.

Instant profiles

Instant Profiles are customer profiles that are automatically created following a payment. If a customer's name is collected from their payment card and a matching profile doesn't already exist within your directory, Square will create an Instant Profile. Future purchases made with that card will update the customer's profile with new payment details and other activity with your business.

While instant profiles can be merged with explicit customer profiles in the Square Dashboard, merging does not retroactively link completed transactions to the new, explicit profile (the customer_id field is still empty).

Customer profiles and cash transactions

The Square Point of Sale application will attempt to implicitly link cash tenders to existing customer profiles based on the provided receipt email or phone number. Implicit links to customer profiles shows up in the Square Point of Sale application and Square Dashboard.