> 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 Customer Groups GET https://api.bigcommerce.com/stores/{store_hash}/v2/customer_groups Returns a list of *Customer Groups*. Default sorting is by customer-group ID, from lowest to highest. **Note:** The default rate limit for this endpoint is 40 concurrent requests. Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/management/customers/v2/customer-groups/get-customer-groups ## 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` | ### 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` (double, optional) — Number of pages. - `limit` (double, optional) — Count per page. - `name` (string, optional) — Filter customer groups by exact name match. - `name:like` (string, optional) — Filter customer groups by name, using a fuzzy matching method. - `is_default` (boolean, optional) — Filter by customers who sign up are added to this group by default. - `date_created` (datetime, optional) — Filter customer groups by date_created. `date_created=2018-09-05T13:43:54` - `date_created:max` (string, optional) — Filter customer groups by maximum date_created. `date_created:max=2018-09-10` - `date_created:min` (datetime, optional) — Filter customer groups by date_created. `date_created:min=2018-09-05` - `date_modified` (datetime, optional) — Filter customer groups by date_modified. `date_modified=2018-09-05T13:45:03` - `date_modified:min` (datetime, optional) — Filter customer groups by minimum date_modified. `date_modified:min=2019-09-04T:00:00:00` or `date_modified:min=2019-09-04` - `date_modified:max` (datetime, optional) — Filter customer groups by maximum date_modified. `date_modified:max=2018-09-05T13:45:03` or `date_modified:max=2019-09-04` - `is_group_for_guests` (boolean, optional) — Filter whether the group is for guests. There can only be one customer group for guests at a time. ### Headers - `Accept` (string, required, default: application/json) — The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body. ## Response ### 200 OK - `list of customerGroup_Full` ## Types ### customerGroup_Full When creating a customer group category discount using the API it defaults to "products in this category and its subcategories". In the [store control panel](https://support.bigcommerce.com/s/article/Customer-Groups#pricing), this can be changed to either "products in this category only" or "products in this category and its subcategories". There are currently no settings to change this behavior with the API. - `id` (integer, optional) — ID of the customer group. - `name` (string, optional) — Name of the group. - `is_default` (boolean, optional) — Determines whether new customers are assigned to this group by default. - `category_access` (categoryAccessLevel_Full, optional) - `discount_rules` (CustomerGroupFullDiscountRules, optional) - `date_created` (string, optional) — Date on which the customer group was created. - `date_modified` (string, optional) — Date on which the customer group was last modified. - `is_group_for_guests` (boolean, optional) — Describes whether the group is for guests. There can only be one customer group for guests at a time. ### categoryAccessLevel_Full - `type` (enum, optional) — + `all` - Customers can access all categories + `specific` - Customers can access a specific list of categories + `none` - Customers are prevented from viewing any of the categories in this group. - Allowed values: `all`, `specific`, `none` - `categories` (list of integer, optional) — Is an array of category IDs and should be supplied only if `type` is specific. ### CustomerGroupFullDiscountRules ## Examples **Response** ```json [ { "id": 1, "name": "Wholesale", "is_default": false, "category_access": { "type": "all", "categories": [ 18, 19, 23, 34 ] }, "discount_rules": [ { "amount": "5.0000", "method": "percent", "price_list_id": 3, "type": "price_list" } ], "date_created": {}, "date_modified": {}, "is_group_for_guests": true } ] ``` **SDK Code** ```python import requests url = "https://api.bigcommerce.com/stores/store_hash/v2/customer_groups" headers = { "Accept": "application/json", "X-Auth-Token": "" } response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.bigcommerce.com/stores/store_hash/v2/customer_groups'; const options = { method: 'GET', headers: {Accept: 'application/json', '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/v2/customer_groups" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Accept", "application/json") 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/v2/customer_groups") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Accept"] = 'application/json' 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/v2/customer_groups") .header("Accept", "application/json") .header("X-Auth-Token", "") .asString(); ``` ```php request('GET', 'https://api.bigcommerce.com/stores/store_hash/v2/customer_groups', [ 'headers' => [ 'Accept' => 'application/json', 'X-Auth-Token' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v2/customer_groups"); var request = new RestRequest(Method.GET); request.AddHeader("Accept", "application/json"); request.AddHeader("X-Auth-Token", ""); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Accept": "application/json", "X-Auth-Token": "" ] let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v2/customer_groups")! 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() ```