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.
- For credit and debit cards on file, use the Cards API with the Customers API, Payments API, Web Payments SDK, and In-App Payments SDK.
- For gift cards on file, use the Gift Cards API with the Customers API.
Using the Customers API to retrieve, save, or 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
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:
{
"card": {
"id": "ccof:uFfUBcvleXzBEXAMPLE",
"card_brand": "VISA",
"last_4": "5858",
"exp_month": 5,
"exp_year": 2022,
"cardholder_name": "John Doe",
"billing_address": {
"address_line_1": "123 Main Street",
"locality": "San Francisco",
"administrative_district_level_1": "CA",
"postal_code": "94103",
"country": "US"
}
}
}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.
Warning
Using the Customers API to get cards on file is deprecated and will be retired at Square API version 2024-12-18.
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:
{ "customer": { "id": "TNQC0TYTWMRSFFQ157KEXAMPLE", "created_at": "2020-11-12T03:51:06.371Z", "updated_at": "2020-11-12T03:51:06Z", "cards": [ { "id": "ccof:uFfUBcvleXzBEXAMPLE", "card_brand": "AMERICAN_EXPRESS", "last_4": "6550", "exp_month": 1, "exp_year": 2023, "cardholder_name": "John Doe", "billing_address": { "address_line_1": "123 Main Street", "locality": "San Francisco", "administrative_district_level_1": "CA", "postal_code": "94103", "country": "US" } }, { "id": "ccof:gg06jEeQodywEXAMPLE", "card_brand": "MASTERCARD", "last_4": "9029", "exp_month": 1, "exp_year": 2023 } ], "given_name": "Amelia", "family_name": "Earhart", ... } }
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 (specified as cents in amount_money.amount):
Create payment
If the operation is successful, Square returns a 200 OK response with the new payment.
{
"payment": {
"id": "dG4ee1fVu3yAuO0sMM4m56EXAMPLE",
"created_at": "2022-05-28T00:44:41.032Z",
"updated_at": "2022-05-28T00:44:41.185Z",
"amount_money": {
"amount": 2515,
"currency": "USD"
},
"status": "COMPLETED",
"delay_duration": "PT168H",
"source_type": "CARD",
"card_details": {
"status": "CAPTURED",
"card": {
"card_brand": "AMERICAN_EXPRESS",
"last_4": "6550",
"exp_month": 1,
"exp_year": 2025,
"fingerprint": "sq-1-9nRcYRrqbyICxeh8CzwO3tVT9ZCOTRYl6Oz6fMZpaBepMG7MIQPmOU578dQEXAMPLE",
"card_type": "CREDIT",
"prepaid_type": "NOT_PREPAID",
"bin": "371263"
},
"entry_method": "ON_FILE",
"cvv_status": "CVV_NOT_CHECKED",
"avs_status": "AVS_ACCEPTED",
"statement_description": "SQ *DEFAULT TEST ACCOUNT"
},
"location_id": "EF6D9CEXAMPLE",
"order_id": "Y4j2ECeeGNVIMNAxaJuyiDEXAMPLE",
"customer_id": "TNQC0TYTWMRSFFQ157KEXAMPLE",
"total_money": {
"amount": 2515,
"currency": "USD"
},
"approved_money": {
"amount": 2515,
"currency": "USD"
},
"receipt_number": "dG4e",
"receipt_url": "https://squareupsandbox.com/receipt/preview/dG4ee1fVu3yAuO0sMM4m56EXAMPLE",
"delay_action": "CANCEL",
"delayed_until": "2022-06-04T00:44:41.032Z",
"application_details": {
"square_product": "ECOMMERCE_API",
"application_id": "sandbox-sq0idb-ioiyW39PwreFzwXEXAMPLE"
},
"version_token": "WXvk1ZKd3SDMQf7NwaPvFGTK15GyItPrEUe5gYEXAMPLE"
}
}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 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:
If you don't have the customer ID, call SearchCustomers to find the customer profile you want to link to and then get the
idfrom the search results. An easy way to find a customer profile is to search by email address or search by phone number.Call CreateOrder to create an order with a customer ID, as shown in the following example request:
Create order
The
customer_idfield 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.{ "order": { "id": "8Kd1p0cf14W6nBrvbw8RM0EXAMPLE", "location_id": "EF6D9CEXAMPLE", "created_at": "2020-05-27T20:23:27.168Z", "updated_at": "2020-05-27T20:23:27.168Z", "state": "OPEN", "version": 1, "total_tax_money": { "amount": 0, "currency": "USD" }, "total_discount_money": { "amount": 0, "currency": "USD" }, "total_tip_money": { "amount": 0, "currency": "USD" }, "total_money": { "amount": 0, "currency": "USD" }, "total_service_charge_money": { "amount": 0, "currency": "USD" }, "net_amounts": { "total_money": { "amount": 0, "currency": "USD" }, "tax_money": { "amount": 0, "currency": "USD" }, "discount_money": { "amount": 0, "currency": "USD" }, "tip_money": { "amount": 0, "currency": "USD" }, "service_charge_money": { "amount": 0, "currency": "USD" } }, "source": { "name": "Sunset service" }, "customer_id": "TNQC0TYTWMRSFFQ157KEXAMPLE" } }Now that the customer is linked to the order, you can call SearchOrders and provide the customer ID in the
customer_filterquery 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.
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_idwhen 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_idand 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 thecustomer_idis added to the payment. If Square cannot find a matching customer profile and cannot create an instant profile, thecustomer_idfield 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 Square 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 Square Dashboard. The delay doesn't occur if the buyer is a returning customer.
Similarly, these orders might not include a
customer_idwhen retrieved using the Orders API. Instead of relying on this field for your integration, consider using thecustomer_idfield 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_idsquery filter in yourSearchOrdersrequest. To obtain these IDs, subscribe tocustomer.createdwebhook events and check whether the notifications contain theevent_context.mergefield. 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.