Learn more about how the Square Customers API processes information.
Docs Home
Dev Essentials
Payments Commerce Customers Staff Merchants
Partnerships
Release notes

Docs

Docs Home
Dev Essentials
Payments
Commerce
Customers
Staff
Merchants
Partnerships
Release notes
Docs
Customers API

Customers API Workflows

Learn more about how the Square Customers API processes information.

Link to section
Basic process flow

The Customers API is a RESTful web service hosted on Square servers. You can use the Customers API to create and manage customer profiles for Square sellers, including membership in customer groups.

Creating a customer profile typically includes the following steps:

  1. The frontend collects customer information with the customer's consent using a form created by the developer. Square does not provide a prebuilt form for this purpose.

  2. The backend packages the customer's phone number or email address as a SearchCustomers request object and sends it to the SearchCustomers endpoint. This step is recommended to avoid creating duplicate customer profiles.

  3. Square processes the request:

    • If the request succeeds: Square returns a list of matching Customer objects or an empty object ({}) if none are found.

    • If the request fails: Square returns any errors that occurred as an Error[].

  4. If no matching customer profiles are found, the backend packages the customer information as a CreateCustomer request object and sends it to the CreateCustomer endpoint.

  5. Square processes the request:

    • If the request succeeds: Square returns a Customer object and invokes a customer.created webhook event.

    • If the request fails: Square returns any errors that occurred as an Error[].

  6. The frontend displays results for the customer.

A diagram showing the basic process flow when creating a customer profile.

For more information about creating and managing customer profiles, including example requests and responses, see Manage Customer Profiles. Or, check out the getCustomerID function in the Bookings API Sample App (Node.js) to see a sample implementation of this workflow.

Link to section
Process flow for cards on file

Warning

Using the Customers API to manage credit and debit cards on file is deprecated. To save a card on file, you should use CreateCard in the Cards API or CreateTerminalAction in the Terminal API. For more information, see the deprecated CreateCustomerCard endpoint migration notes.

You can save a card on file for a particular customer by sending a card_nonce and customer_id to the CreateCustomerCard endpoint (deprecated). You can then use the returned card ID to process payments. The Web Payments SDK or In-App Payments SDK, Customers API, and CreatePayment endpoint from the Payments API work together to process card-on-file payments.

Important

Your application must use the Web Payments SDK or In-App Payments SDK to collect card information.

Saving a card on file typically includes the following steps:

  1. The frontend uses the Web Payments SDK or In-App Payments SDK to collect card information and generate a secure payment token. The frontend should also collect contact information for the customer at this point. Customers must consent to saving their card and contact information.

  2. The backend packages the contact information as a CreateCustomer request object and sends it to the CreateCustomer endpoint.

  3. Square returns a Customer object with an id. This value is used as the customer_id in the CreatePayment request.

  4. The backend packages a CreateCustomerCard request object containing the customer_id and card_nonce and sends it to the CreateCustomerCard endpoint (deprecated). The card_nonce value is the payment token generated in step 1.

  5. Square returns a CustomerCard object with an id. This value is used as the customer_card_id in the CreatePayment request.

  6. The backend packages a CreatePayment request object with the customer_card_id and a customer_id and sends it to the CreatePayment endpoint.

    To link a customer to a payment or save a card on file, you must create or retrieve a customer profile before packaging the CreatePayment request. Customer profiles cannot be linked to completed payments.

A diagram showing the process flow for saving a card on file.

Link to section
Related topics

On this page
We've made improvements to our docs.
Prefer the old format?