Integrate Customer Profiles with Other Services

Integrating the Customers API with other Square APIs can help Square sellers improve the customer-relationship management experience and simplify transactions. For example, you can use the Cards API to save a card on file so customers can easily make card payments. Another example is to use the Orders API to link customers with orders and then search for orders using the customer ID.

Link to section

Manage cards on file

Using the Customers API to manage cards on file is deprecated and replaced with functionality provided by the Cards API and Gift Cards API.

Link to section

Save cards on file (deprecated)

Warning

Using the Customers API to save cards on file is deprecated. For more information, see the migration notes.

If you're using OAuth, you need CUSTOMERS_WRITE permission to save a card on file and PAYMENTS_WRITE permission to process payments with the saved card. Cards on file are automatically updated on a monthly basis to confirm that they are valid and can be charged.

Important

Always ask customers for permission before saving their card information. For example, include a checkbox in your purchase flow that the customers can select to specify that they want to save their card information for future purchases.

Linking cards on file without obtaining customer permission can result in your application being disabled without notice.

To save a card on file for a customer, you must first create a payment token, which is a secure card payment token that can be generated using the Web Payments SDK or In-App Payments SDK. For information about using Strong Customer Authentication (SCA) to also generate a verification token with the Web Payments SDK or In-App Payments SDK, see Strong Customer Authentication Overview.

The following request calls the CreateCustomerCard endpoint (deprecated) in the Customers API. The request uses an example customer ID and the Sandbox test value (cnon:card-nonce-ok). If you specify the billing_address.postal_code field when using the test value, you must set the value to 94103.

Create customer card

If the operation is successful, the card specified in the card_nonce field of the request is saved on file for the customer. The saved card information is returned as the payload of a 200 OK response, as shown in the following example response:

The saved card can be used for payments. For information about using a card on file in a CreatePayment request, see Process flow for cards on file.

Link to section

Get cards on file (deprecated)

Warning

Using the Customers API to get cards on file is deprecated. For more information, see the migration notes.

Cards on file are stored in the cards field (deprecated) of a customer profile. To get cards on file, call the RetrieveCustomer or ListCustomers endpoint in the Customers API.

The following request calls the RetrieveCustomer endpoint using an example customer ID.

Retrieve customer

The following is an excerpt of an example response for a customer profile that has two cards on file listed in the cards field:

Link to section

Delete cards on file (deprecated)

Warning

Using the Customers API to delete cards on file is deprecated. For more information, see the migration notes.

To remove a previously stored card from a customer profile, call the DeleteCustomerCard endpoint (deprecated) in the Customers API. The following request uses an example customer ID and card ID:

Delete customer card

Link to section

Charge cards on file

To take a payment from a credit, debit, or gift card on file, call CreatePayment and provide the card ID and the customer ID. Providing a customer ID is required for payments from a credit or debit card on file and recommended for payments from a gift card on file.

If you need to get the customer ID, call SearchCustomers to search customer profiles by phone number, email address, or other supported attribute. Then, you can call ListCards using the customer_id filter to get the credit or debit card ID or call ListGiftCards using the customer_id filter to get the gift card ID.

The following CreatePayment request charges a credit card on file for $25.15 (specified as cents in amount_money.amount):

Create payment

If the operation is successful, Square returns a 200 OK response with the new payment.

For more information about credit or debit card on file payments, see Card on file as a payment source. For more information about gift cards on file payments, see Taking payments from gift cards on file.

Link to section

Link customers to orders

Linking customers to orders allows you to view order history by customer. You can link a customer to an order by specifying a customer ID in the CreateOrder request. If needed, you can call the SearchCustomers endpoint to get the ID of the target customer profile.

The following steps show how to link a customer to a new order and search orders using a customer ID:

  1. If you don't have the customer ID, call SearchCustomers to find the customer profile you want to link to and then get the id from the search results. An easy way to find a customer profile is to search by email address or search by phone number.

  2. Call CreateOrder to create an order with a customer ID, as shown in the following example request:

    Create order

    The customer_id field in the following example response shows that the customer is linked to the new order. You can modify the order later to add more details, as needed.

  3. Now that the customer is linked to the order, you can call SearchOrders and provide the customer ID in the customer_filter query filter, as shown in the following example request:

    Search orders

    For more information about using the Orders API to create and manage orders, see Orders API: What It Does.

    Note

    Watch the Sandbox 101: Linking Customer Data video to see how you can show linked customer, order, and card-on-file data in a dashboard using Rails.

Link to section

Customer assignments for orders and payments

You should be aware of the following considerations regarding customer assignments:

  • Linking orders and payments to customers helps provide a more seamless experience for Square sellers and their customers. When possible, you should specify the customer_id when you create a payment or an order. If you don't have the customer ID, use information collected from the customer to call SearchCustomers to find a matching customer profile. If one cannot be found, call CreateCustomer to create a new profile using the information collected from the customer.

    If your application doesn't collect any information from the customer, you can omit the customer_id and rely on Square's inference to find the best matching customer profile or to create an instant profile to associate with the payment. Note that this process is asynchronous and might take some time before the customer_id is added to the payment. If Square cannot find a matching customer profile and cannot create an instant profile, the customer_id field of the payment remains unset. In this case, the transaction isn't associated with a customer in Square products, such as Square Point of Sale and the Seller Dashboard.

  • Orders made from a Square Online store might not be immediately associated with a customer. When a new buyer places an order from a Square Online store, Square attempts to create an instant profile in the seller's Customer Directory and then assign the profile to the order. This process is asynchronous and might take some time to update the customer information when viewed on the Transactions page in Square Point of Sale or the Seller Dashboard. The delay doesn't occur if the buyer is a returning customer.

    Similarly, these orders might not include a customer_id when retrieved using the Orders API. Instead of relying on this field for your integration, consider using the customer_id field of the corresponding payment, which is more likely to be populated. If this field isn't specified when the payment is created, Square attempts to set it by finding a matching customer profile or creating an instant profile.

  • Sellers can merge duplicate customer profiles that represent the same customer. The merge operation deletes the existing customer profiles and creates a new aggregated customer profile with a new ID. Currently, searching for orders using the new customer ID doesn't return any orders that were made using a previous customer ID.

    As a workaround, you should store all previous customer IDs and provide them in the customer_ids query filter in your SearchOrders request. To obtain these IDs, subscribe to customer.created webhook events and check whether the notifications contain the event_context.merge field. This field is included when the customer profile is created from a merge operation and contains the IDs of all affected customer profiles. For more information, see Notifications for customer profile merge events.

Note

If the customer_id isn't set for a payment made using a non-payment-card payment method (such as gift card, ACH, or Cash App), Square doesn't attempt to find or create a customer profile to populate the customer_id.

Link to section

Customer ID integration points

The following Square objects contain a customer ID, which is commonly specified when the object is created:

The following List or Search requests support querying by customer ID: