> 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 Price Lists

GET https://api.bigcommerce.com/stores/{store_hash}/v3/pricelists

Returns a list of *Price Lists*. Optional parameters can be passed in.

Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/management/price-lists/get-price-lists

## Authentication

- `X-Auth-Token` header (required) — ### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Products | modify | `store_v2_products` | | Products | read-only | `store_v2_products_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

- `name` (string, optional) — Filter items by name.
- `date_created` (datetime, optional) — Filter items by date_created.
- `date_modified` (datetime, optional) — Filter items by date_modified. For example `v3/catalog/products?date_last_imported:min=2018-06-15`
- `page` (integer, optional) — Specifies the page number in a limited (paginated) list of products.
- `limit` (integer, optional) — Controls the number of items per page in a limited (paginated) list of products. If you provide only a limit, the API returns both paginations while applying that limit.
- `before` (string, optional) — A cursor that can be used for backwards pagination. Will fetch results before the position corresponding to the cursor. Cannot be used with the 'page' query parameter. Cannot be used with the 'after' query parameter.
- `after` (string, optional) — A cursor that can be used for forwards pagination. Will fetch results after the position corresponding to the cursor. Cannot be used with the 'page' query parameter. Cannot be used with the 'before' query parameter.
- `id:in` (list of integer, optional) — Filter results to those whose ID is in this list.
- `name:like` (string, optional) — Filter results to those whose name contains this value.
- `date_created:max` (string, optional) — Filter results to those created on or before this date.
- `date_created:min` (string, optional) — Filter results to those created on or after this date.
- `date_modified:max` (string, optional) — Filter results to those modified on or before this date.
- `date_modified:min` (string, optional) — Filter results to those modified on or after this date.

### 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

- `data` (list of PricelistsGetResponsesContentApplicationJsonSchemaDataItems, optional)
- `meta` (PricelistsGetResponsesContentApplicationJsonSchemaMeta, optional) — 'Contains data about paginating the response via cursors. If no pagination details are specified or if you only provide a limit, then both properties will be present. When a 'before' or 'after' cursor is provided, only the 'cursor_pagination' property will be present. When a 'page' parameter is provided, only the offset based 'pagination' property will be present.'

## Types

### PricelistsGetResponsesContentApplicationJsonSchemaDataItems

Specifies the Common Price List properties.

- `name` (string, required) — The unique name of the Price List. Required in a POST request.
- `id` (integer, optional) — The unique numeric ID of the `Price List`; this number increments sequentially.
- `date_created` (datetime, optional) — The date on which the `Price List` was created.
- `date_modified` (datetime, optional) — The date on which the `Price List` was created.
- `active` (boolean, optional) — Boolean value that specifies whether this `Price List` and its prices are active or not. Defaults to `true`.
- `layers` (list of LayerItem, optional) — Fallback price lists evaluated in order when a price record is not found in this price list. Maximum five layers. Inactive layers are skipped during price resolution but remain assigned.

### PricelistsGetResponsesContentApplicationJsonSchemaMeta

'Contains data about paginating the response via cursors. If no pagination details are specified or if you only provide a limit, then both properties will be present. When a 'before' or 'after' cursor is provided, only the 'cursor_pagination' property will be present. When a 'page' parameter is provided, only the offset based 'pagination' property will be present.'

- `pagination` (PricelistsGetResponsesContentApplicationJsonSchemaMetaPagination, optional) — Data related to the response, including pagination and collection totals.
- `cursor_pagination` (PricelistsGetResponsesContentApplicationJsonSchemaMetaCursorPagination, optional)

### LayerItem

A fallback price list layer.

- `price_list_id` (integer, optional) — The ID of the fallback price list.

### PricelistsGetResponsesContentApplicationJsonSchemaMetaPagination

Data related to 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.

### PricelistsGetResponsesContentApplicationJsonSchemaMetaCursorPagination

- `count` (integer, optional) — Total number of items in the collection response.
- `per_page` (integer, optional) — The number of items that can be returned per page, determined by the limit parameter—whether explicitly set, defaulted, or capped at the maximum limit.
- `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` (PricelistsGetResponsesContentApplicationJsonSchemaMetaCursorPaginationLinks, optional) — Pagination links for the previous and next parts of the whole collection.

### PricelistsGetResponsesContentApplicationJsonSchemaMetaCursorPaginationLinks

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.

## Examples

**Response**

```json
{
  "data": [
    {
      "name": "Warehouse",
      "id": 1,
      "date_created": "2022-02-26T17:33:11Z",
      "date_modified": "2022-05-08T14:05:27Z",
      "active": true,
      "layers": []
    },
    {
      "name": "B2B",
      "id": 2,
      "date_created": "2022-02-26T17:37:01Z",
      "date_modified": "2022-02-26T17:37:01Z",
      "active": true,
      "layers": [
        {
          "price_list_id": 5
        }
      ]
    },
    {
      "name": "Wholesale",
      "id": 3,
      "date_created": "2022-04-05T16:05:12Z",
      "date_modified": "2022-04-05T16:05:12Z",
      "active": true,
      "layers": []
    }
  ],
  "meta": {
    "pagination": {
      "total": 3,
      "count": 3,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1
    },
    "cursor_pagination": {
      "count": 8,
      "per_page": 50,
      "start_cursor": "Nw==",
      "end_cursor": "MTQ=",
      "links": {}
    }
  }
}
```

**SDK Code**

```python Response
import requests

url = "https://api.bigcommerce.com/stores/store_hash/v3/pricelists"

headers = {
    "Accept": "application/json",
    "X-Auth-Token": "<apiKey>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript Response
const url = 'https://api.bigcommerce.com/stores/store_hash/v3/pricelists';
const options = {
  method: 'GET',
  headers: {Accept: 'application/json', 'X-Auth-Token': '<apiKey>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Response
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bigcommerce.com/stores/store_hash/v3/pricelists"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "application/json")
	req.Header.Add("X-Auth-Token", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Response
require 'uri'
require 'net/http'

url = URI("https://api.bigcommerce.com/stores/store_hash/v3/pricelists")

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"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java Response
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.bigcommerce.com/stores/store_hash/v3/pricelists")
  .header("Accept", "application/json")
  .header("X-Auth-Token", "<apiKey>")
  .asString();
```

```php Response
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.bigcommerce.com/stores/store_hash/v3/pricelists', [
  'headers' => [
    'Accept' => 'application/json',
    'X-Auth-Token' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Response
using RestSharp;

var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/pricelists");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "application/json");
request.AddHeader("X-Auth-Token", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift Response
import Foundation

let headers = [
  "Accept": "application/json",
  "X-Auth-Token": "<apiKey>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v3/pricelists")! 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()
```