# List price lists (v2)

URL: https://docs.sparklayer.io/developers/api/pricing/get-price-lists-v2
Operation: `GET /api/v2/price-lists` (operationId `getPriceLists`)
OpenAPI spec: https://docs.sparklayer.io/openapi/pricing.yaml

Returns price lists one page at a time. Use `page` (default `1`) and `page_size` (default `100`, maximum `250`) to page through the results, `order_by` to sort them (for example `name:asc` or `updated_at:desc`), and `source` to filter by a comma-separated list of sources. Results are returned in `data`, with a `pagination` object giving `total`, `per_page`, `current_page` and `total_pages`.

Use this endpoint rather than `GET /api/v1/price-lists`, which returns every price list in one unpaginated array.

`GET /api/v2/price-lists`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v2/price-lists" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | integer | | The page of results to fetch. Default: `1`. Min 1. |
| `page_size` | integer | | Number of records per page. Default: `100`. Min 1, max 250. |
| `order_by` | string | | Field to order the search results by. Default: `name:asc`. Pattern: `^(name\|created_at\|updated_at):(asc\|desc)$`. |
| `source` | ("custom" \| "integration" \| "platform")[] | | Only return price lists from these sources, as a comma-separated list: `custom` (set up in the SparkLayer Dashboard), `integration` (created by an external integration) or `platform` (reserved for the eCommerce platform). Defaults to all three. Default: `["custom","integration","platform"]`. |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Example: `jones-climbing` |

### Responses

#### 200: One page of price lists in `data`, with the paging details in `pagination`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object[] | | |
| `data[].slug` | string | | Slug. Length: min 1, max 64. |
| `data[].name` | string | | Name. Length: min 1, max 128. |
| `data[].currency_code` | string | | ISO 4217 currency code. Length: min 3, max 3. |
| `data[].source` | "custom" \| "platform" \| "integration" | | Integration should be used by external parties, custom is provided to any price lists setup in the dashboard and platform is reserved for the eCommerce platform. Default: `custom`. |
| `data[].tax_inclusive_display` | boolean | | When true, storefronts display prices on this price list inclusive of the per-SKU display_tax_rate, labelled as tax inclusive. This changes presentation only - prices are still stored and transacted net. SKUs on the list with no rate, or a rate of 0, display their net price and are still labelled tax inclusive. Default: `false`. |
| `data[].rules` | object[] | | Length: max 5. |
| `data[].rules[].source_price_list_slug` | string | | Source PriceList slug. Length: min 1, max 64. |
| `data[].rules[].adjustment_percentage` | number | | Adjustment percent expressed as a decimal fraction between 0 and 1 - E.g. 15% should be set as 0.15. Min 0, max 1. |
| `data[].rules[].adjustment_direction` | "plus" \| "minus" | | Adjustment direction (plus, minus) |
| `data[].rules[].currency_exchange_rate` | number \| null | | Exchange rate between the currency of the source price list and the price list to which this rule belongs. If null, the rate will be determined automatically based on current market rates. Min 0.000001. |
| `pagination` | object | | |
| `pagination.total` | integer | | The total number of available records |
| `pagination.per_page` | integer | | The number of records returned per page |
| `pagination.current_page` | integer | | The current page of results returned |
| `pagination.total_pages` | integer | | the total number of available pages |

```json
{
  "data": [
    {
      "slug": "base-list",
      "name": "Base Price List",
      "currency_code": "GBP",
      "source": "custom",
      "tax_inclusive_display": false,
      "rules": [
        {
          "source_price_list_slug": "base-list",
          "adjustment_percentage": 0.103333,
          "adjustment_direction": "plus",
          "currency_exchange_rate": 1.254324
        }
      ]
    }
  ],
  "pagination": {
    "total": 0,
    "per_page": 0,
    "current_page": 0,
    "total_pages": 0
  }
}
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://docs.sparklayer.io/tech-docs"
}
```