Learn more about how the Square Customers API processes information.
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:
The frontend collects customer information with the customer's consent using a form created by the developer. Square doesn't provide a prebuilt form for this purpose. For more information, see Best Practices for Collecting Information.
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.
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[]
.
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.
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[]
.
The frontend displays results for the customer.
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.
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:
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.
The backend packages the contact information as a CreateCustomer
request object and sends it to the CreateCustomer endpoint.
Square returns a Customer
object with an id
. This value is used as the customer_id
in the CreatePayment
request.
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.
Square returns a CustomerCard
object with an id
. This value is used as the customer_card_id
in the CreatePayment
request.
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.