Customers API

Integrate Customer Profiles with Other Services

Maintaining customer profiles in a Square account not only improves the seller's experience in managing customer relationships, but also helps enable frictionless transactions when the Customers API is integrated with other Square services or APIs.

An example of such integrations involves calling the Customers API to save a card on file for a customer so that the card can be applied in the Payments services. Another example is to link a customer with an order and then use the Orders API to search orders by customer ID.

Manage cards on file Permalink Get a link to this section

You can use the Customers API to save cards on file, get cards on file, and delete cards on file.

Save cards on file Permalink Get a link to this section

Warning

Using the Customers API to save cards on file is deprecated. For more information, see Migrate to the Cards API and Gift Cards API.

If you are 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 check 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 nonce, 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, see SCA for the Web Payments SDK or SCA for the In-App 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 nonce (cnon:card-nonce-ok). If you specify the billing_address.postal_code field when using the test nonce, you must set the value to 94103.

Create Customer Card
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
curl https://connect.squareupsandbox.com/v2/customers/TNQC0TYTWMRSFFQ157Kexample/cards \
  -X POST \
  -H 'Square-Version: 2021-07-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "card_nonce": "cnon:card-nonce-ok",
    "cardholder_name": "John Doe",
    "billing_address": {
      "postal_code": "94103",
      "country": "US",
      "first_name": "John",
      "last_name": "Doe",
      "locality": "San Francisco",
      "address_line_1": "123 Main Street",
      "administrative_district_level_1": "CA"
    }
  }'

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.

Get cards on file Permalink Get a link to this section

Warning

Using the Customers API to get cards on file is deprecated. For more information, see Migrate to the Cards API and Gift Cards API.

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
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/customers/TNQC0TYTWMRSFFQ157Kexample \
  -H 'Square-Version: 2021-07-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

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",
    ...
  }
}

Delete cards on file Permalink Get a link to this section

Warning

Using the Customers API to delete cards on file is deprecated. For more information, see Migrate to the Cards API and Gift Cards API.

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
  • 1
  • 2
  • 3
  • 4
  • 5
curl https://connect.squareupsandbox.com/v2/customers/TNQC0TYTWMRSFFQ157Kexample/cards/ccof%3AuFfUBcvleXzBexample \
  -X DELETE \
  -H 'Square-Version: 2021-07-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

Migrate to the Cards API and Gift Cards API Permalink Get a link to this section

Using the Customers API to manage customer cards on file is deprecated. Use the following information to find the recommended replacements in the Cards API or Gift Cards API (beta).

Deprecated CreateCustomerCard endpoint Permalink Get a link to this section

Deprecated in version: 2021-06-16
Retired in version: 2022-06-16

The CreateCustomerCard endpoint is deprecated. You should use one of the following endpoints instead:

Deprecated DeleteCustomerCard endpoint Permalink Get a link to this section

Deprecated in version: 2021-06-16
Retired in version: 2022-06-16

The DeleteCustomerCard endpoint is deprecated. You should use one of the following endpoints instead:

Deprecated Customer.cards field Permalink Get a link to this section

Deprecated in version: 2021-06-16
Retired in version: 2022-06-16

The cards field on the Customer object is deprecated. You should use one of the following endpoints instead:

Charge cards on file Permalink Get a link to this section

The following example request charges the customer (with the ID of TNQC0TYTWMRSFFQ157Kexample) the amount of $25.15 (as specified in amount_money.amount in cents) on the previously saved card on file (as identified by source_id):

Create Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2021-07-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount_money": {
      "amount": 2515,
      "currency": "USD"
    },
    "idempotency_key": "{UNIQUE_KEY}",
    "source_id": "ccof:customer-card-id-ok",
    "customer_id": "TNQC0TYTWMRSFFQ157Kexample"
  }'

When the operation is successful, a payload similar to the following is returned in a 200 OK response:

{
  "payment": {
    "id": "dG4ee1fVu3yAuO0sMM4m56example",
    "created_at": "2020-05-28T00:44:41.032Z",
    "updated_at": "2020-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": 2022,
        "fingerprint": "sq-1-9nRcYRrqbyICxeh8CzwO3tVT9ZCOTRYl6Oz6fMZpaBepMG7MIQPmOU578dQexample",
        "card_type": "CREDIT",
        "prepaid_type": "NOT_PREPAID",
        "bin": "371263"
      },
      "entry_method": "ON_FILE",
      "cvv_status": "CVV_ACCEPTED",
      "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"
    },
    "receipt_number": "dG4e",
    "receipt_url": "https://squareupsandbox.com/receipt/preview/dG4ee1fVu3yAuO0sMM4m56example",
    "delay_action": "CANCEL",
    "delayed_until": "2020-06-04T00:44:41.032Z"
  }
}

For more information, see Card on file as a payment source.

Link customers to orders Permalink Get a link to this section

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 examples show how to link a customer to a new order and search orders using a customer ID.

  • If you do not have the customer ID, call SearchCustomers to find the customer profile that you want to link to the order and 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.

  • Call CreateOrder to create an order with the customer ID, as shown in the following example:

    Create Order
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    curl https://connect.squareupsandbox.com/v2/orders \
      -X POST \
      -H 'Square-Version: 2021-07-21' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "order": {
          "location_id": "EF6D9Cexample",
          "customer_id": "TNQC0TYTWMRSFFQ157Kexample",
          "state": "OPEN",
          "source": {
            "name": "Sunset service"
          }
        },
        "idempotency_key": "{UNIQUE_KEY}"
      }'

    The following example response shows that the specified customer (with the ID of TNQC0TYTWMRSFFQ157Kexample) 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 use the customer_filter search query filter with the linked customer ID and the location ID of the order, as shown in the following example:

    Search Orders
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    curl https://connect.squareupsandbox.com/v2/orders/search \
      -X POST \
      -H 'Square-Version: 2021-07-21' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "query": {
          "filter": {
            "customer_filter": {
              "customer_ids": [
                "TNQC0TYTWMRSFFQ157Kexample"
              ]
            }
          }
        },
        "location_ids": [
          "EF6D9Cexample"
        ]
      }'

Customer assignments for orders and payments Permalink Get a link to this section

In the Seller Dashboard, transaction activity is based on the customer_id of the order and other related settings, but the customer_id of the payment is ignored. For example, if the order does not have a customer assignment, the transaction's Paid by field might not display the customer who is assigned to the payment. To reliably link transactions to customers in the Seller Dashboard, make sure to specify the customer_id field in your CreateOrder request.

In addition, omitting this field on the Order object might result in the creation of new instant profiles that are linked to the payment.

Related topics Permalink Get a link to this section