Retrieve Customer Profiles

Learn how to retrieve and list customers profiles stored in a Square account.

Overview

Developers can use the following endpoints in the Customers API to get detailed information about customer profiles stored in a seller's Customer Directory:

RetrieveCustomer - Retrieves a single customer profile by ID.
BulkRetrieveCustomers - Retrieves multiple customer profiles by IDs.
ListCustomers - Lists the customer profiles in a seller account.

Note

The SearchCustomers endpoint in the Customers API can be used to find and view customer profiles based on phone number, email address, or other query filters. For more information, see Search for Customer Profiles.

Several list and search endpoints in other Square APIs return objects that are associated with a customer, such as orders, bookings, cards on file, and custom attributes. For more information, see Customer ID integration points.

Link to section

Retrieve a single customer profile by ID

To get details about a single customer profile, call RetrieveCustomer and provide the customer ID, as shown in the following request:

Retrieve customer

Note

The BulkRetrieveCustomers endpoint can also be used to retrieve a single customer.

If the RetrieveCustomer operation is successful, Square returns a 200 status code and a customer field that contains the requested customer profile. For example:

{
  "customer": {
    "id": "TNQC0TYTWMRSFFQ157KK4V7MVR",
    "created_at": "2020-04-27T17:28:50.073Z",
    "updated_at": "2020-05-27T04:43:53Z",
    "given_name": "John",
    "family_name": "Doe",
    "company_name": "Company",
    "email_address": "[email protected]",
    "address": {
      "address_line_1": "123 Main Street",
      "locality": "City",
      "postal_code": "12345",
      "country": "US"
    },
    "phone_number": "+12065551212",
    "birthday": "0000-01-13",
    "preferences": {
      "email_unsubscribed": false
    },
    "creation_source": "THIRD_PARTY",
    "segment_ids": [
      "499XKDADA7682.REACHABLE"
    ],
    "version": 0
  }
}

Link to section

Retrieve multiple customer profiles by IDs

To retrieve 1 to 100 customer profiles in a bulk operation, call BulkRetrieveCustomers and provide a list of customer IDs.

The following BulkRetrieveCustomers request retrieves three customer profiles:

Bulk retrieve customers

For bulk operations, Square processes the retrieved requests individually and returns a map of responses.

If the BulkRetrieveCustomers operation is successfully processed, Square returns a 200 status code and a responses map of key-value pairs that represent the responses for individual retrieve requests.

For each key-value pair, the key is a customer ID that was specified in the request and the value is either the requested customer profile (if the request succeeded) or error information (if the request failed). For example:

{
  "responses": {
    "5CZ99Q9SD8C71SGFD4CR96CBCT": {
      "errors": [
        {
          "code": "NOT_FOUND",
          "detail": "Customer with ID `5CZ99Q9SD8C71SGFD4CR96CBCT` not found.",
          "category": "INVALID_REQUEST_ERROR"
        }
      ]
    },
    "TNQC0TYTWMRSFFQ157KK4V7MVR": {
      "customer": {
        "id": "TNQC0TYTWMRSFFQ157KK4V7MVR",
        "created_at": "2020-04-27T17:28:50.073Z",
        "updated_at": "2020-05-27T04:43:53Z",
        "given_name": "John",
        "family_name": "Doe",
        "company_name": "Company",
        "email_address": "[email protected]",
        "address": {
          "address_line_1": "123 Main Street",
          "locality": "City",
          "postal_code": "12345",
          "country": "US"
        },
        "phone_number": "+12065551212",
        "birthday": "0000-01-13",
        "preferences": {
          "email_unsubscribed": false
        },
        "creation_source": "THIRD_PARTY",
        "segment_ids": [
          "499XKDADA7682.REACHABLE"
        ],
        "version": 0
      }
    },
    "PE6CW5359K3J913DH3PF4PREF8": {
      "customer": {
        "id": "PE6CW5359K3J913DH3PF4PREF8",
        "created_at": "2024-01-20T00:32:34.43Z",
        "updated_at": "2024-01-20T00:32:34Z",
        "given_name": "Vera",
        "family_name": "Sara",
        "email_address": "[email protected]",
        "phone_number": "+14167779999",
        "preferences": {
          "email_unsubscribed": false
        },
        "creation_source": "THIRD_PARTY",
        "version": 1
      }
    }
  }
}

Note that the responses might not be returned in the same order as the list of customer IDs sent to BulkRetrieveCustomers.

Link to section

List customer profiles in a seller account

To list the customer profiles in the seller's Customer Directory, call ListCustomers.

List customers

If the ListCustomers operation is successfully processed, Square returns returns a 200 response that contains a list of customer profiles or an empty object ({}) if no profiles exist.

{
  "customers": [
    {
      "id": "A537H7KAQWSAF8M8EM1Y23E16M",
      "created_at": "2021-10-28T20:19:07.692Z",
      "updated_at": "2024-01-09T20:14:21Z",
      "cards": [
        {
          "id": "ccof:oG9wEmGAvoAnrBGt3GB",
          "card_brand": "VISA",
          "last_4": "5858",
          "exp_month": 10,
          "exp_year": 2023,
          "cardholder_name": "Amelia Earhart",
          "billing_address": {
            "address_line_1": "500 Electric Ave",
            "locality": "New York",
            "administrative_district_level_1": "NY",
            "postal_code": "94103",
            "country": "US"
          }
        },
        {
          "id": "gftc:06c30c2b9772458a9e87b2880ee2ce1a",
          "card_brand": "SQUARE_GIFT_CARD",
          "last_4": "0895",
          "exp_month": 12,
          "exp_year": 2050,
          "billing_address": {
            "postal_code": "94103"
          }
        }
      ],
      "given_name": "Amelia",
      "family_name": "Earhart",
      "email_address": "[email protected]",
      "address": {
        "address_line_1": "123 Main St",
        "locality": "Seattle",
        "administrative_district_level_1": "WA",
        "postal_code": "98121",
        "country": "US"
      },
      "phone_number": "1-212-555-4240",
      "note": "a customer on seller account",
      "reference_id": "YOUR_REFERENCE_ID",
      "company_name": "ACME",
      "preferences": {
        "email_unsubscribed": false
      },
      "creation_source": "THIRD_PARTY",
      "segment_ids": [
        "8QJTJCE6AZSN6.REACHABLE",
        "8QJTJCE6AZSN6.CARDS_ON_FILE",
        "gv2:8H24YRM74H2030XWJWP9F0MAEW",
        "gv2:4TR2NFVP8N63D9K1FZ5E62VD78"
      ],
      "version": 4
    },
    {
      "id": "XVN84NCJS9QWX0N202WX90TJ5R",
      "created_at": "2024-01-09T23:45:20.789Z",
      "updated_at": "2024-01-09T23:45:20Z",
      "given_name": "Sara",
      "family_name": "Vera",
      "email_address": "[email protected]",
      "address": {
        "address_line_1": "292 Adelaide St",
        "locality": "Toronto",
        "administrative_district_level_1": "ON",
        "country": "CA"
      },
      "phone_number": "+14167779999",
      "preferences": {
        "email_unsubscribed": false
      },
      "creation_source": "THIRD_PARTY",
      "birthday": "2000-10-10",
      "segment_ids": [
        "8QJTJCE6AZSN6.REACHABLE"
      ],
      "version": 0
    },
    {
      "id": "T4BKEYWKMS6G14BQ06Z961H7QW",
      "created_at": "2020-10-28T19:13:36.64Z",
      "updated_at": "2021-03-08T22:56:28Z",
      "cards": [
        {
          "id": "ccof:QIIqI2o1oQYoq25k4GB",
          "card_brand": "MASTERCARD",
          "last_4": "9029",
          "exp_month": 1,
          "exp_year": 2023,
          "billing_address": {
            "postal_code": "94103"
          }
        }
      ],
      "given_name": "John",
      "family_name": "Doe",
      "email_address": "[email protected]",
      "phone_number": "2065551012",
      "note": "\n// Merged on 2021/03/08. Following fields were not transferred to the current customer:\nFirst Name: Doe\nEmail Address: [email protected]\nPhone Number: (206) 555-1011\n// Merged on 2021/03/08.",
      "preferences": {
        "email_unsubscribed": false
      },
      "creation_source": "MERGE",
      "segment_ids": [
        "8QJTJCE6AZSN6.REACHABLE",
        "8QJTJCE6AZSN6.CARDS_ON_FILE",
        "8QJTJCE6AZSN6.LOYALTY_ALL",
        "gv2:8H24YRM74H2030XWJWP9F0MAEW",
        "gv2:4TR2NFVP8N63D9K1FZ5E62VD78"
      ],
      "version": 1
    },
    {
      "id": "6ZK40WV46EM8M2AVC9ZEF7B018",
      "created_at": "2024-01-20T00:32:34.533Z",
      "updated_at": "2024-01-20T12:46:09Z",
      "given_name": "Silva",
      "family_name": "Antonio",
      "email_address": "[email protected]",
      "address": {
        "address_line_1": "1001 Broadway Ave",
        "locality": "Toronto",
        "administrative_district_level_1": "ON",
        "country": "CA"
      },
      "phone_number": "+14375552222",
      "note": "Birthday Club member",
      "reference_id": "refid",
      "preferences": {
        "email_unsubscribed": false
      },
      "creation_source": "THIRD_PARTY",
      "birthday": "0000-07-07",
      "segment_ids": [
        "8QJTJCE6AZSN6.REACHABLE"
      ],
      "version": 2
    },
    {
      "id": "T9Q21K8PA5MQY3PAZZT2WGGVC0",
      "created_at": "2023-04-12T20:38:05.255Z",
      "updated_at": "2023-04-12T20:38:05Z",
      "phone_number": "2085550988",
      "preferences": {
        "email_unsubscribed": false
      },
      "creation_source": "LOYALTY",
      "segment_ids": [
        "8QJTJCE6AZSN6.LOYALTY_ALL"
      ],
      "version": 0
    },
    {
      "id": "Q8002JB4YQ5SB8A9FPE2476ADMM30NG",
      "created_at": "2022-10-14T22:51:57.306Z",
      "updated_at": "2022-10-14T22:51:57Z",
      "phone_number": "4255550000",
      "preferences": {
        "email_unsubscribed": false
      },
      "creation_source": "LOYALTY",
      "segment_ids": [
        "8QJTJCE6AZSN6.LOYALTY_ALL"
      ],
      "version": 0
    },
    {
      "id": "Q8002VV1DJTRG0TF3A55MAWPZR2EA80",
      "created_at": "2022-07-16T20:15:11.123Z",
      "updated_at": "2022-07-16T20:15:11Z",
      "phone_number": "6095550923",
      "preferences": {
        "email_unsubscribed": false
      },
      "creation_source": "LOYALTY",
      "segment_ids": [
        "8QJTJCE6AZSN6.LOYALTY_ALL"
      ],
      "version": 0
    }
  ]
}

Only customer profiles that contain public information (given_name, family_name, company_name, email_address, or phone_number) are included in the results. Customer profiles with no public information are excluded.

Link to section

Sorting the results

By default, Square sorts the results by concatenating the given_name and family_name fields of each customer profile and returning them in ascending order. If neither field is set, a string comparison is performed using one of the following fields in the following order: company_name, email_address, phone_number.

You can optionally use the sort_field query parameter to sort by the created_at field and the sort_order query parameter to sort by descending order.

List customers

Link to section

Setting a page size

You can also optionally specify a maximum page size in the request. The following example request uses the limit query parameter to specify a maximum page size of three results. The default page size is 100.

List customers

Note

Square treats the limit value as advisory and might return more or fewer results.

The following is an excerpt of an example paged response with the count field:

{
  "customers": [
    {
      // customer 1 fields
    },
    {
      // customer 2 fields
    },
    {
      // customer 3 fields
    }
  ],
  "cursor": "PNEhVUKBuTOuRIZoUcX5VQ...UE1cVyWmbXhoY",
  "count": 13293
}

When the number of results exceeds the page size, the response includes a cursor field. To get the next page of results, send the previous ListCustomers request and include the cursor query parameter set to the cursor returned in the response.

List customers

To retrieve all customer profiles, use the new cursor value returned in each response for the next request, until the response doesn't include a cursor field.

Link to section

Getting the customer count

The preceding example also sets the optional count parameter to true, which directs Square to return a count field that contains the total number of customer profiles in the directory.

Only customer profiles that contain public information (given_name, family_name, company_name, email_address, or phone_number) are included in the count. Customer profiles with no public information are excluded.

Link to section

Considerations

Use SearchCustomers with a large customer base - Although the ListCustomers endpoint can be used to retrieve all customers in the Customer Directory, it might not be practical with a large customer base. Using the SearchCustomers endpoint with one or more query filters is a more efficient method for retrieving customers when you don't know their IDs. For more information, see Search for Customer Profiles.
Synchronizing customer data - To synchronize customer data from the Customer Directory to your application, you can use customer webhooks to be notified of changes in addition to polling periodically with the SearchCustomers or ListCustomers endpoint.
Custom attributes not included in Customer API responses - The RetrieveCustomer, BulkRetrieveCustomers, and ListCustomers endpoints cannot be used to retrieve custom attributes for customer profiles. However, you can use the customer ID with the RetrieveCustomerCustomAttribute or ListCustomerCustomAttributes endpoint to retrieve or list custom attributes for a specified customer profile, including seller-defined custom fields. For more information, see Create and Manage Customer Custom Attributes.
Customer profiles have multiple sources - Customer profiles returned in RetrieveCustomer, BulkRetrieveCustomers, and ListCustomers responses include customers created using the Square Dashboard, Square Point of Sale, the Customers API, and other flows. For example, a customer profile might be created for loyalty accounts and instant profiles might be created for payments. For information about how to create customer profiles using the Customers API, see Manage Customer Profiles.
Sometimes Square creates instant profiles that have no public information. These instant profiles aren't included in ListCustomers or SearchCustomers responses.

Link to section

Docs

Retrieve Customer Profiles

On this page

Overview

Note

Retrieve a single customer profile by ID

Note

Retrieve multiple customer profiles by IDs

List customer profiles in a seller account

Sorting the results

Setting a page size

Note

Getting the customer count

Considerations

See also

On this page