Learn more about how the Square Customers API processes information.
Customers API

Customers API Workflows

Basic process flow Permalink Get a link to this section

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.

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

  3. Square 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. The frontend displays results for the customer.

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

Process flow for cards on file Permalink Get a link to this section

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. For more information, see Cards API Overview or Migrate to the Cards API and Gift Cards API.

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.

Related topics Permalink Get a link to this section

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

On this page