Drive Growth

Customers API Overview

Use the Customers API to manage customer information and save credit card information for card-on-file payments.

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 transactions.
  • The Customers API cannot be used to send customers emails.
  • The Customers API does not check for duplicate records during Customer creation.
  • The Customers API cannot link customers to transactions processed through the Checkout API.
  • The Customers API cannot filter customer records by location or the employee who created the record.
  • Customer profiles are not instantly created. On average, Customer profiles can be retrieved 0.4 seconds after they are created.
  • Filtering for customer searches is currently limited to creation source and timestamps for creation and last update.

Applications using the Customers API need permission to make calls on the merchant's behalf. If using OAuth, request CUSTOMERS_READ and CUSTOMERS_WRITE permissions.

Applications built for personal use need only a personal access token.

How to use it — Customers API data model

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.

Handling customer data responsibly

If your application uses customer contact information, be sure to use that information judiciously. Here are some tips on how to handle customer data responsibly:

  • Respect customer email preferences. If they have opted out of marketing emails, keep CustomerPreferences false.
  • Do not store personally identifying information (PII) like name, email, and physical address without explicit consent.
  • Do not store sensitive or payment info in the note field.
  • Always use secure HTTPS for your own services to protect user information in transit.

How it works — Customers API process flow

Customers process overview

The Customers API is a RESTful web service hosted on Square servers. It creates and manages customer information and card on file payment for recurring payments.

Creating a customer profile typically includes the following steps:

  1. Frontend collects customer information with customer consent.
  2. Backend packages the information as a CreateCustomer request object and sends it to the CreateCustomer endpoint.
  3. The Square server processes the request.
    • If the request succeeds — the Square server returns a Customer object.
    • If the request fails — the Square server returns an error.
  4. Frontend displays results for the customer.
Process flow 1

You can also save a card on file for a particular customer by sending a card_nonce and customer_id to the CreateCustomerCard endpoint. You can then use the returned card ID to process payments. The Customers API, SqPaymentForm, and the Charge endpoint from the Transactions API work together to process card-on-file payments.

Saving a card on file typically includes the following steps:

  1. The Square payment form collects card information and uses it to generate a card nonce. We recommend that you also collect customer contact information at this point with your own form.
  2. The client server packages the customer information as a CreateCustomer request object and sends it to the CreateCustomer endpoint.
  3. The Square server returns a Customer object with an id. This value will be used as the customer_id in the Charge request.
  4. The client server packages a CreateCustomerCard request object containing the customer_id and the card nonce generated by the Square payment form.
  5. The Square server returns a CustomerCard object with an id. This value will be used as the customer_card_id in the Charge request.
  6. The client server packages a Charge request with both a customer_card_id and a customer_id instead of a card_nonce.
Process flow 2

Customer objects cannot be linked to completed transactions.

To link a customer to a transaction or to save a card on file, you must create or retrieve a customer profile before packaging the Charge request.

Instant profiles

Instant Profiles are customer profiles that are automatically created following a transaction. 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 transaction 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 customer profiles with cash transactions 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, and can be returned through the Transactions API even if the transaction is not explicitly linked by the customer ID in the transaction object.

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 (2017/12/18) through an eCommerce site using the Customers API.
  • Customer B — their profile was created 2 months ago (2018/10/18) through an eCommerce site using the Customers API.
  • Customer C — their profile was created 2 weeks ago (2018/12/04) 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 (2018/06/18 to 2018/12/17)
  • Include customer profiles updated in the last week (2018/12/11 to 2018/12/17).

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 (2018/12/11 to 2018/12/17).

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 (2018/12/11 to 2018/12/17).

will return all 3 Customer profiles.

Next
Customers API Setup >

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow