Customers API Workflows

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:

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

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.

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.

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.

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.

• Manage Customer Profiles
• Retrieve Customer Profiles
• Search for Customer Profiles
• Integrate Customer Profiles with Other Services
• Use Customer Webhooks
• Frontend and Backend Development