> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # List Customers GET https://api.bigcommerce.com/stores/{store_hash}/v3/customers Returns a list of Customers. Optional filter parameters can be passed in. **Notes** Attribute names are not available on the customer object. Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/management/customers/v3/get-customers ## Authentication - `X-Auth-Token` header (required) — ### 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). ## Request ### Path parameters - `store_hash` (string, required) — Permanent ID of the BigCommerce store. ### Query parameters - `page` (integer, optional) — Page number (`page` will be ignored if you provide `before` or `after` in the request). For example `page=1`. - `limit` (double, optional) — Items count per page. `limit=50` - `id:in` (list of integer, optional) — Filter items by ID. `id:in=4,5,6` - `company:in` (list of string, optional) — Filter items by company. `company:in=bigcommerce,commongood` - `customer_group_id:in` (list of string, optional) — Filter items by customer_group_id. `customer_group_id:in=5,6` - `date_created` (datetime, optional) — Filter items by date created, for example, `2024-05-14T09:34:00` or `2024-05-14`. - `date_created:max` (string, optional) — 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:min` (datetime, optional) — Filter items by date created for example, `2024-05-14T09:34:00` or `2024-05-14`. Returns customers created after this date. - `date_modified` (datetime, optional) — Filter items by date modified, for example, `2024-05-14T09:34:00` or `2024-05-14`. - `date_modified:min` (string, optional) — 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:max` (datetime, optional) — Filter items by maximum date modified, for example, `2024-05-14T09:34:00` or `2024-05-14`. Returns customers modified before this date. - `email:in` (list of string, optional) — Filter items by email. `email:in=janedoe@example.com` - `name:in` (list of string, optional) — Filter items by first_name and last_name. `name=james moriarty` - `name:like` (list of string, optional) — Filter items by substring in first_name and last_name. `name:like=moriarty,sherlock` Concatenates the first_name and last_name fields. - `phone:in` (string, optional) — Filter items by phone number. `phone:in=555-55-5555` - `registration_ip_address:in` (list of integer, optional) — 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` - `include` (list of enum, optional) — 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` - Allowed values: `addresses`, `storecredit`, `attributes`, `formfields`, `shopper_profile_id`, `segment_ids` - `sort` (enum, optional) — 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` - Allowed values: `date_created:asc`, `date_created:desc`, `last_name:asc`, `last_name:desc`, `date_modified:asc`, `date_modified:desc` - `after` (string, optional) — 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`. - `before` (string, optional) — 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 ### 200 Get Customer Collection Response - `data` (list of customer_Full, optional) - `meta` (_metaCollectionWithCursorPagination, optional) — 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 The optional filter parameter was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - `status` (integer, optional) — The HTTP status code for the error. - `title` (string, optional) — The error title. - `type` (string, optional) — The error type. - `errors` (ErrorDetail, optional) — Error detail response payload for the BigCommerce API. ## Types ### customer_Full - `email` (string, optional) — The email of the customer. Must be unique. - `first_name` (string, optional) — The first name of the customer. - `last_name` (string, optional) — The last name of the customer. - `company` (string, optional) — The company of the customer. - `phone` (string, optional) — The phone number of the customer. - `registration_ip_address` (string, optional) — The IP address from which this customer was registered. - `notes` (string, optional) — The customer notes. - `tax_exempt_category` (string, optional) — The tax exempt category code for the customer. - `customer_group_id` (integer, optional) — ID of the group which this customer belongs to. - `id` (integer, optional) — The unique numeric ID of the customer. - `date_modified` (datetime, optional) — The date on which the customer was modified. - `date_created` (datetime, optional) — The date of which the customer was created. - `address_count` (integer, optional) — Total number of customer addresses. - `attribute_count` (integer, optional) — Total number of customer attributes. - `authentication` (CustomerFullAuthentication, optional) - `addresses` (list of address_Full, optional) — Array of customer addresses. Limited to 10. - `attributes` (list of attribute_Full, optional) — Array of customer attributes. Limited to 10. - `form_fields` (list of formFieldValue_Customer, optional) — Array of form fields. Controlled by `formfields` parameter. - `store_credit_amounts` (list of CustomerStoredCreditAmountsItems, optional) — Store credit. - `accepts_product_review_abandoned_cart_emails` (boolean, optional) — Determines if the customer is signed up to receive either product review or abandoned cart emails or receive both emails. - `origin_channel_id` (integer, optional) — Channel ID of the customer that has created the form. - `channel_ids` (list of any, optional) — Array of channel ids the Customer has access to. ### _metaCollectionWithCursorPagination 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. - `pagination` (Pagination, optional) — Data about the response, including pagination and collection totals. - `cursor_pagination` (CursorPagination, optional) — Data about cursor pagination. ### ErrorDetail Error detail response payload for the BigCommerce API. ### CustomerFullAuthentication - `force_password_reset` (boolean, optional) — If `true`, this customer will be forced to change password on next login. ### address_Full - `first_name` (string, required) — The first name of the customer address. - `last_name` (string, required) — The last name of the customer address. - `address1` (string, required) — The address 1 line. - `city` (string, required) — The city of the customer address. - `state_or_province` (string, required) — The state or province name. - `postal_code` (string, required) — The postal code of the customer address. - `country_code` (string, required) — The country code of the customer address. - `customer_id` (integer, required) — The customer ID. - `id` (integer, required) — The unique numeric ID of the address. - `company` (string, optional) — The company of the customer address. - `address2` (string, optional) — The address 2 line. - `phone` (string, optional) — The phone number of the customer address. - `address_type` (enum, optional) — The address type. Residential or Commercial. - Allowed values: `residential`, `commercial` - `country` (string, optional) — The country name of the customer address. - `form_fields` (list of formFieldValue, optional) — Array of form fields. Controlled by `formfields` parameter. ### attribute_Full - `attribute_id` (integer, optional) — Attribute ID. - `attribute_value` (string, optional) — Attribute value. - `customer_id` (integer, optional) — Customer ID. - `date_created` (datetime, optional) — The date the customer attribute was created. - `date_modified` (datetime, optional) — The date the customer attribute was modified. - `id` (integer, optional) — Attribute value ID. ### formFieldValue_Customer - `name` (string, required) — The form field name. - `value` (FormFieldValueCustomerValue, required) - `customer_id` (integer, required) ### CustomerStoredCreditAmountsItems - `amount` (float, optional) ### Pagination Data about the response, including pagination and collection totals. - `total` (integer, optional) — Total number of items in the result set. - `count` (integer, optional) — Total number of items in the collection response. - `per_page` (integer, optional) — The amount of items returned in the collection per page, controlled by the limit parameter. - `current_page` (integer, optional) — The page you are currently on within the collection. - `total_pages` (integer, optional) — The total number of pages in the collection. - `links` (Links, optional) — Pagination links for the previous and next parts of the whole collection. ### CursorPagination Data about cursor pagination. - `count` (integer, optional) — Total number of items in the collection response. - `per_page` (integer, optional) — The amount of items returned in the collection per page, controlled by the limit parameter. - `start_cursor` (string, optional) — A string representing the starting point of the current page in the collection - `end_cursor` (string, optional) — A string representing the ending point of the current page in the collection. - `links` (Links, optional) — Pagination links for the previous and next parts of the whole collection. ### formFieldValue - `name` (string, required) — The form field name. - `value` (FormFieldValueValue, required) ### FormFieldValueCustomerValue ### Links Pagination links for the previous and next parts of the whole collection. - `previous` (string, optional) — Link to the previous page returned in the response. - `current` (string, optional) — Link to the current page returned in the response. - `next` (string, optional) — Link to the next page returned in the response. ### FormFieldValueValue ## Examples **Response** ```json { "data": [ { "email": "string", "first_name": "string", "last_name": "string", "company": "string", "phone": "string", "registration_ip_address": "string", "notes": "string", "tax_exempt_category": "string", "customer_group_id": 1, "id": 1, "date_modified": "2024-01-15T09:30:00Z", "date_created": "2024-01-15T09:30:00Z", "address_count": 1, "attribute_count": 1, "authentication": { "force_password_reset": true }, "addresses": [ { "first_name": "string", "last_name": "string", "address1": "string", "city": "string", "state_or_province": "string", "postal_code": "string", "country_code": "string", "customer_id": 1, "id": 1, "company": "string", "address2": "string", "phone": "string", "address_type": "residential", "country": "string", "form_fields": [ { "name": "color", "value": "blue" } ] } ], "attributes": [ { "attribute_id": 2, "attribute_value": "Yes", "customer_id": 1, "date_created": "2024-01-15T09:30:00Z", "date_modified": "2024-01-15T09:30:00Z", "id": 2 } ], "form_fields": [ { "name": "color", "value": "blue", "customer_id": 1 } ], "store_credit_amounts": [ { "amount": 43.15 } ], "accepts_product_review_abandoned_cart_emails": true, "origin_channel_id": 1, "channel_ids": [ null ] } ], "meta": { "pagination": { "total": 1, "count": 1, "per_page": 1, "current_page": 1, "total_pages": 1, "links": { "previous": "string", "current": "string", "next": "string" } }, "cursor_pagination": { "count": 1, "per_page": 1, "start_cursor": "string", "end_cursor": "string", "links": { "previous": "string", "current": "string", "next": "string" } } } } ``` **SDK Code** ```python import requests url = "https://api.bigcommerce.com/stores/store_hash/v3/customers" headers = {"X-Auth-Token": ""} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.bigcommerce.com/stores/store_hash/v3/customers'; const options = {method: 'GET', headers: {'X-Auth-Token': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.bigcommerce.com/stores/store_hash/v3/customers" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("X-Auth-Token", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.bigcommerce.com/stores/store_hash/v3/customers") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["X-Auth-Token"] = '' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.bigcommerce.com/stores/store_hash/v3/customers") .header("X-Auth-Token", "") .asString(); ``` ```php request('GET', 'https://api.bigcommerce.com/stores/store_hash/v3/customers', [ 'headers' => [ 'X-Auth-Token' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/customers"); var request = new RestRequest(Method.GET); request.AddHeader("X-Auth-Token", ""); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["X-Auth-Token": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v3/customers")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```