Use Customers API: Integrate With Other Services

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

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 payment token for the card and can be generated using the Square payment form or In-App Payments SDK. To use Strong Customer Authentication (see SCA in Payment Form or see SCA for In-App Payments SDK ), you must generate a verification token.

The following request calls the CreateCustomerCard endpoint 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-03-17' \
  -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

Cards on file are stored in the cards field 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-03-17' \
  -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

To remove a previously stored card from a customer profile, call the DeleteCustomerCard endpoint 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-03-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

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-03-17' \
  -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"
  }
}

Link customers to orders Permalink Get a link to this section

To link a customer to an order, you create an order for the specified customer. You need to provide the customer's ID as the input. If you do not have the ID, you can call the SearchCustomers endpoint to find the customer profiles meeting specified queries and then get the customer ID from the search result.

As an additional prerequisite, you need ORDERS_READ permission to create orders, if you use OAuth.

The following examples show how to link a customer to a new order:

  • Find the customer profile to link to an order. An easy way to find the ID of a customer is to search for the customer profile by the customer's email address or phone number. Then, inspect the result to extract the ID value. For an example of how to do this, see Search for Customer Profiles.

  • Create an order with the customer ID.

    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-03-17' \
      -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 specified customer (with the ID of TNQC0TYTWMRSFFQ157Kexample) is now linked to the newly created order (with the ID of 8Kd1p0cf14W6nBrvbw8RM0example), which you can modify later to add more details.

    {
      "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"
      }
    }
    

    After linking a customer to an order, you can easily search for the order using customer_filter with the linked customer ID (customer_id) and the order's location_id. This is 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-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "query": {
          "filter": {
            "customer_filter": {
              "customer_ids": [
                "TNQC0TYTWMRSFFQ157Kexample"
              ]
            }
          }
        },
        "location_ids": [
          "EF6D9Cexample"
        ]
      }'

    Related topics Permalink Get a link to this section