Applies to: Customers API
Learn how the Customers API integrates with other Square APIs.
Integrating the Customers API
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
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
Delete customer card
To take a payment from a credit, debit, or gift card on file, call CreatePayment
If needed, call SearchCustomers to search customer profilescustomer_id parameter to get the credit or debit card ID or ListGiftCardscustomer_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
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
SearchCustomers to get theidof 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 CreateCustomerCreateCustomer to create a new profile using information collected from the customer.Call CreateOrder
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
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
SearchCustomers to get theidof 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 CreateCustomerCreateCustomer to create a new profile using information collected from the customer.Call CreatePayment
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
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
payment links don't include acustomer_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 profileusing 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
SearchOrders or RetrieveOrderRetrieveOrder to get order details. Don't use thecustomer_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
GetPayment using the payment ID and copy thecustomer_idfield.Get payment
Call RetrieveCustomer
RetrieveCustomer or BulkRetrieveCustomersBulkRetrieveCustomers to get customer information.
To get customers that are directly linked to orders, call SearchOrderscustomer_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 linkcustomer_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
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