For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dev Portal
DocsAPI ReferenceLearnCommunityChangelog
DocsAPI ReferenceLearnCommunityChangelog
    • About Our APIs
  • REST
    • Overview
      • Overview
        • Abandoned Carts
        • Carts
        • Channels
        • Checkouts
        • Currencies
          • V3
              • GETList Customers
              • POSTCreate Customers
              • PUTUpdate Customers
              • DELDelete Customers
          • V2
        • Customer Segmentation
        • Geography
        • Infrastructure Hosting
        • Inventory
        • Orders
        • Order Operations
        • Pickup
        • Pickup Methods
        • Pickup Options
        • Pricing
        • Price Lists
        • Promotions
        • Promotion Settings
        • Redirects
        • Scripts
        • Settings
        • Shipping
        • Sites
        • Subscribers
        • System Logs
        • Tax
        • Wishlists
      • Payments
  • GraphQL
    • Overview
  • MCP
    • Overview
Dev Portal
LogoLogo
RESTAdminManagementCustomersV3

List Customers

GET
https://api.bigcommerce.com/stores/:store_hash/v3/customers
GET
/stores/:store_hash/v3/customers
$curl https://api.bigcommerce.com/stores/store_hash/v3/customers \
>     -H "X-Auth-Token: <apiKey>"
1{
2  "data": [
3    {
4      "email": "string",
5      "first_name": "string",
6      "last_name": "string",
7      "company": "string",
8      "phone": "string",
9      "registration_ip_address": "string",
10      "notes": "string",
11      "tax_exempt_category": "string",
12      "customer_group_id": 1,
13      "id": 1,
14      "date_modified": "2024-01-15T09:30:00Z",
15      "date_created": "2024-01-15T09:30:00Z",
16      "address_count": 1,
17      "attribute_count": 1,
18      "authentication": {
19        "force_password_reset": true
20      },
21      "addresses": [
22        {
23          "first_name": "string",
24          "last_name": "string",
25          "address1": "string",
26          "city": "string",
27          "state_or_province": "string",
28          "postal_code": "string",
29          "country_code": "string",
30          "customer_id": 1,
31          "id": 1,
32          "company": "string",
33          "address2": "string",
34          "phone": "string",
35          "address_type": "residential",
36          "country": "string",
37          "form_fields": [
38            {
39              "name": "color",
40              "value": "blue"
41            }
42          ]
43        }
44      ],
45      "attributes": [
46        {
47          "attribute_id": 2,
48          "attribute_value": "Yes",
49          "customer_id": 1,
50          "date_created": "2024-01-15T09:30:00Z",
51          "date_modified": "2024-01-15T09:30:00Z",
52          "id": 2
53        }
54      ],
55      "form_fields": [
56        {
57          "name": "color",
58          "value": "blue",
59          "customer_id": 1
60        }
61      ],
62      "store_credit_amounts": [
63        {
64          "amount": 43.15
65        }
66      ],
67      "accepts_product_review_abandoned_cart_emails": true,
68      "origin_channel_id": 1,
69      "channel_ids": [
70        null
71      ]
72    }
73  ],
74  "meta": {
75    "pagination": {
76      "total": 1,
77      "count": 1,
78      "per_page": 1,
79      "current_page": 1,
80      "total_pages": 1,
81      "links": {
82        "previous": "string",
83        "current": "string",
84        "next": "string"
85      }
86    },
87    "cursor_pagination": {
88      "count": 1,
89      "per_page": 1,
90      "start_cursor": "string",
91      "end_cursor": "string",
92      "links": {
93        "previous": "string",
94        "current": "string",
95        "next": "string"
96      }
97    }
98  }
99}

Returns a list of Customers. Optional filter parameters can be passed in.

Notes

Attribute names are not available on the customer object.

Was this page helpful?
Previous

Customers V3

Next

Create Customers

Built with

Authentication

X-Auth-Tokenstring
### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Customers | modify | `store_v2_customers` | | Customers | read-only | `store_v2_customers_read_only` | | Stored Payment Instruments | modify | `store_stored_payment_instruments` | | Stored Payment Instruments | read-only | `store_stored_payment_instruments_read_only` | ### Authentication header | Header | Argument | Description | |:-------|:---------|:------------| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

Path parameters

store_hashstringRequired
Permanent ID of the BigCommerce store.

Query parameters

pageintegerOptional

Page number (page will be ignored if you provide before or after in the request). For example page=1.

limitdoubleOptional

Items count per page. limit=50

id:inlist of integersOptional

Filter items by ID. id:in=4,5,6

company:inlist of stringsOptional

Filter items by company. company:in=bigcommerce,commongood

customer_group_id:inlist of stringsOptional

Filter items by customer_group_id. customer_group_id:in=5,6

date_createddatetimeOptional

Filter items by date created, for example, 2024-05-14T09:34:00 or 2024-05-14.

date_created:maxstringOptional

Filter items by maximum date created, for example, 2024-05-14T09:34:00 or 2024-05-14. Returns customers created before this date.

date_created:mindatetimeOptional

Filter items by date created for example, 2024-05-14T09:34:00 or 2024-05-14. Returns customers created after this date.

date_modifieddatetimeOptional

Filter items by date modified, for example, 2024-05-14T09:34:00 or 2024-05-14.

date_modified:minstringOptional

Filter items by minimum date modified, for example, 2024-05-14T09:34:00 or 2024-05-14. Returns customers modified after this date.

date_modified:maxdatetimeOptional

Filter items by maximum date modified, for example, 2024-05-14T09:34:00 or 2024-05-14. Returns customers modified before this date.

email:inlist of stringsOptional

Filter items by email. email:in=janedoe@example.com

name:inlist of stringsOptional

Filter items by first_name and last_name. name=james moriarty

name:likelist of stringsOptional

Filter items by substring in first_name and last_name. name:like=moriarty,sherlock Concatenates the first_name and last_name fields.

phone:instringOptional

Filter items by phone number. phone:in=555-55-5555

registration_ip_address:inlist of integersOptional

Filter items by registration_ip_address. If the customer was created using the API, then registration address is blank. registration_ip_address:in=12.345.6.789

includelist of enumsOptional
Indicates whether to include customer sub-resources: * `addresses` - customer addresses * `storecredit` - store credit * `attributes` - customer attributes and address attributes * `formfields` - customer and address form fields * `shopper_profile_id` - the ID of the shopper profile associated with the customer (Beta) * `segment_ids`- segments the customer belongs to (Beta) `include=addresses,storecredit,attributes,formfields,shopper_profile_id,segment_ids`
sortenumOptional
Sort items by date_created, date_modified, or last_name:* `date_created:asc` - date created, ascending* `date_created:desc` - date created, descending* `last_name:asc` - last name, ascending* `last_name:desc` - last name, descending * `date_modified:asc` - date modified, ascending* `date_modified:desc`- date modified, descending Example: `sort=last_name:asc`
afterstringOptional

The cursor reference of the last entry for the previous page. Use the end_cursor value from the last response to get the next page (end_cursor is only returned on the first page or when the request contains query parameter before or after). For example after=eyJpZCI6MjA0fQ.

beforestringOptional

The cursor reference of the first entry for the next page. Use the start_cursor value from the last response to get the previous page (start_cursor is only returned on the first page or when the request contains query parameter before or after). For example before=eyJpZCI6MjA1fQ.

Response

Get Customer Collection Response
datalist of objects
metaobject

Data about the response, including pagination and collection totals. Both pagination and cursor_pagination would be returned in the first page. Only pagination would be returned when page is greater than 1. Only cursor_pagination would be returned when before or after is provided in the request.

Errors

422
Unprocessable Entity Error

OAuth scopes

UI NamePermissionParameter
Customersmodifystore_v2_customers
Customersread-onlystore_v2_customers_read_only
Stored Payment Instrumentsmodifystore_stored_payment_instruments
Stored Payment Instrumentsread-onlystore_stored_payment_instruments_read_only

Authentication header

HeaderArgumentDescription
X-Auth-Tokenaccess_tokenFor more about API accounts that generate access_tokens, see our Guide to API Accounts.

Further reading

For example requests and more information about authenticating BigCommerce APIs, see Authentication and Example Requests.

For more about BigCommerce OAuth scopes, see our Guide to API Accounts.

For a list of API status codes, see API Status Codes.

Indicates whether to include customer sub-resources:

  • addresses - customer addresses
  • storecredit - store credit
  • attributes - customer attributes and address attributes
  • formfields - customer and address form fields
  • shopper_profile_id - the ID of the shopper profile associated with the customer (Beta)
  • segment_ids- segments the customer belongs to (Beta)

include=addresses,storecredit,attributes,formfields,shopper_profile_id,segment_ids

Sort items by date_created, date_modified, or last_name:* date_created:asc - date created, ascending* date_created:desc - date created, descending* last_name:asc - last name, ascending* last_name:desc - last name, descending * date_modified:asc - date modified, ascending* date_modified:desc- date modified, descending Example: sort=last_name:asc