Applies to: Customers API | Cards API | Gift Cards API | Payments API | Web Payments SDK | In-App Payments SDK | Orders API
Learn how the Customers API integrates with other Square APIs.
Integrating the Customers API with other Square APIs can help Square sellers improve the customer-relationship management experience and simplify transactions. For example, integration with the Cards API can facilitate card payments and integration with the Orders API and Payments API can streamline reporting and auditing processes.
Buyers can agree to store their credit, debit, and gift cards for future payments to Square sellers. These cards on file provide a quick and convenient payment method for both buyers and sellers.
The Cards API lets you store, access, and manage credit and debit cards on file. This API integrates with the Customers API, Payments API, Web Payments SDK, In-App Payments SDK, and other Square APIs. For more information, see Cards API.
The Gift Cards API lets you store, access, and manage gift cards on file. This API integrates with the Customers API, Payments API, Gift Card Activities API, and other Square APIs. For more information, see Manage Square Gift Cards on File.
Using the Customers API to manage cards on file is deprecated. For more information, see Migration notes.
Warning
Using the Customers API to save cards on file is deprecated.
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're 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.
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
The stored card can be used for card on file payments.
Warning
Using the Customers API to delete cards on file is deprecated.
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
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 credit or debit cards on file and recommended for payments from gift cards on file.
If needed, call SearchCustomers to search customer profiles by phone number, email address, or other supported attribute to get the customer ID. Then call ListCards using the customer_id parameter to get the credit or debit card ID or ListGiftCards using the customer_id parameter to get the gift card ID.
The following CreatePayment request charges a credit card on file for $25.15 (amount_money.amount is specified in cents):
Create 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.
Linking customers to orders and payments can help provide a more seamless experience for Square sellers and their customers. If your application collects information from the customer, you should specify the customer_id when you create orders and payments.
The following steps show how to link a customer to a new order:
If you need to get the customer ID, call SearchCustomers to get the
idof the customer profile you want to link to. You can search by email address, phone number, or other supported attribute. If a match cannot be found, call CreateCustomer to create a new profile using information collected from the customer.Call CreateOrder and provide the customer ID, as shown in the following example request that creates a simple order:
Create order
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.
The following steps show how to explicitly link a customer to a new payment:
Get the customer ID. This might be the customer that's linked to the order (in the
Order.customer_idfield) or a different customer.If you're not using a customer ID from the order, call SearchCustomers to get the
idof the customer profile you want to link to. You can search by email address, phone number, or other supported attribute. If a match cannot be found, call CreateCustomer to create a new profile using information collected from the customer.Call CreatePayment and provide the customer ID. This example also provides the order ID:
Create payment
Note
If your application doesn't collect any information from the customer, you can omit customer_id and let Square attempt to assign a customer to the payment asynchronously.
Customers can be assigned to payments and orders. When retrieving transaction history for auditing, reporting, and tracking activities, Square recommends relying on Payment.customer_id instead of using the order (or corresponding tenders) because:
Orders might not have a customer assignment. For example, orders made from Square Online stores or generated from payment links don't include a
customer_idfield when retrieved using the Orders API.Payments are more likely to have a customer assignment because Square might populate the
Payment.customer_idfield using inference or by creating an instant profile. Note that this process is asynchronous.Payments are the primary source of truth for payment information. They contain more details than order tenders and provide the most accurate and up-to-date information.
Some orders have multiple payments, and each payment can have a different customer assignment.
Square recommends using this process to get all customers associated with an order:
Call SearchOrders or RetrieveOrder to get order details. Don't use the
customer_filterfilter in theSearchOrdersrequest because not all orders have a customer assignment.Retrieve order
For each order that applies to your use case, iterate through the
order.tendersfield and copytender.idortender.payment_id(if present). Both values represent the ID of the corresponding payment.For each payment, call GetPayment using the payment ID and copy the
customer_idfield.Get payment
Call RetrieveCustomer or BulkRetrieveCustomers to get customer information.
To get customers that are directly linked to orders, call SearchOrders and specify 1 – 10 customer IDs in the customer_filter query parameter. Keep in mind that not all orders have a customer assignment. For more information, see Missing customer assignment.
Search orders
Note that you can also inspect the Order.customer_id field in unfiltered SearchOrders results to find all customer assignments for orders.
Orders made from a Square Online store or generated from a payment link aren't associated with a customer, so these orders don't include a customer_id field when retrieved using the Orders API. Additionally, other integrations might not specify a customer ID when creating orders.
Square recommends using the customer_id field from the corresponding payment or payments instead of relying on Order.customer_id. Payment.customer_id is more likely to be populated because Square attempts to asynchronously assign a customer to a payment when a customer isn't specified.
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. 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.