List Customers

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

Notes

Attribute names are not available on the customer object.

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-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

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