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.

Save cards on file
Permalink Get a link to this section

If you are using OAuth, you need the CUSTOMER_WRITE permission to save a card on file and the PAYMENTS_WRITE permission to process payments with the save 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 SCA for In-App Payments SDK), you must generate a verification token.

In the following example, a test nonce is used in the request body ("card_nonce": "cnon:card-nonce-ok") for the Sandbox environment. The billing_address.post_code value must be 94103.

The following cURL example shows a REST API call to the Create customer card endpoint of the Customers API:

curl https://connect.squareupsandbox.com/v2/customers/TNQC0TYTWMRSFFQ157KK4V7MVR/cards \
  -X POST \
  -H 'Square-Version: 2020-04-22' \
  -H 'Authorization: Bearer {SQUARE_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"
    }
  }'

When the operation is successful, the specified card (as identified by the card_nonce value) is saved on file for the specified customer (as identified by the {customer_id} path parameter value of TNQC0TYTWMRSFFQ157KK4V7MVR). The saved card information is returned as the payload of a 200 OK response, as shown in the following:

{
  "card": {
    "id": "ccof:uFfUBcvleXzBHXiO3GB",
    "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 is ready for charges in ensuing transactions.

Charge cards on file
Permalink Get a link to this section

The following REST API request in cURL charges the customer (as identified by customer_id) $25.15 (as specified in amount_money.amount in cents) on the previously saved card on file (as identified by source_id):

curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2020-04-22' \
  -H 'Authorization: Bearer {SQUARE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount_money": {
      "amount": 2515,
      "currency": "USD"
    },
    "idempotency_key": "78db4919-b281-4061-b9e2-55d379ecaccf",
    "source_id": "ccof:customer-card-id-ok",
    "customer_id": "TNQC0TYTWMRSFFQ157KK4V7MVR"
  }'

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

{
  "payment": {
    "id": "dG4ee1fVu3yAuO0sMM4m56rZp59YY",
    "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-9nRcYRrqbyICxeh8CzwO3tVT9ZCOTRYl6Oz6fMZpaBepMG7MIQPmOU578dQuhLuzNg",
        "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": "EF6D9SACKWBKZ",
    "order_id": "Y4j2ECeeGNVIMNAxaJuyidI6YdPZY",
    "customer_id": "TNQC0TYTWMRSFFQ157KK4V7MVR",
    "total_money": {
      "amount": 2515,
      "currency": "USD"
    },
    "receipt_number": "dG4e",
    "receipt_url": "https://squareupsandbox.com/receipt/preview/dG4ee1fVu3yAuO0sMM4m56rZp59YY",
    "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 Search customers 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 the ORDERS_READ permission to create orders, if you use OAuth.

The following cURL examples show how to link a customer to a new order using the REST API:

  • 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.

curl https://connect.squareup.com/v2/locations/EF6D9SACKWBKZ/orders \
  -X POST \
  -H 'Square-Version: 2020-04-22' \
  -H 'Authorization: Bearer {SQUARE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "order": {
      "location_id": "EF6D9SACKWBKZ",
      "customer_id": "TNQC0TYTWMRSFFQ157KK4V7MVR",
      "state": "OPEN",
      "source": {
        "name": "Sunset service"
      }
    },
    "idempotency_key": "bcb8df5b-15d2-4d3e-99b1-c5995cb0be32"
  }'

The specified customer (with the ID of TNQC0TYTWMRSFFQ157KK4V7MVR ) is now linked to the newly created order (with the ID of 8Kd1p0cf14W6nBrvbw8RM0XWk1YZY), which you can modify later to add more details.

{
  "order": {
    "id": "8Kd1p0cf14W6nBrvbw8RM0XWk1YZY",
    "location_id": "EF6D9SACKWBKZ",
    "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": "TNQC0TYTWMRSFFQ157KK4V7MVR"
  }
}

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 cURL example:

curl https://connect.squareup.com/v2/orders/search \
  -X POST \
  -H 'Square-Version: 2020-04-22' \
  -H 'Authorization: Bearer {SQUARE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "customer_filter": {
          "customer_ids": [
            "TNQC0TYTWMRSFFQ157KK4V7MVR"
          ]
        }
      }
    },
    "location_ids": [
      "EF6D9SACKWBKZ"
    ]
  }'