# Create a price list

URL: https://docs.sparklayer.io/developers/api/pricing/create-a-price-list
Operation: `POST /api/v1/price-lists` (operationId `createPriceList`)
OpenAPI spec: https://docs.sparklayer.io/openapi/pricing.yaml

`slug`, `name` and `currency_code` are required, and `currency_code` must be a valid ISO 4217 code. `source` defaults to `custom`. Returns `400` if a price list with the same slug already exists, or if a rule references a source price list that does not exist.

`POST /api/v1/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 -X POST "https://app.sparklayer.io/api/v1/price-lists" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "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
    }
  ]
}'
```

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`.

### Header parameters

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

### Request body (`application/json`) (required)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | Slug. Length: min 1, max 64. |
| `name` | string | Yes | Name. Length: min 1, max 128. |
| `currency_code` | string | Yes | ISO 4217 currency code. Length: min 3, max 3. |
| `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`. |
| `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`. |
| `rules` | object[] | | Length: max 5. |
| `rules[].source_price_list_slug` | string | | Source PriceList slug. Length: min 1, max 64. |
| `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. |
| `rules[].adjustment_direction` | "plus" \| "minus" | | Adjustment direction (plus, minus) |
| `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. |

```json
{
  "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
    }
  ]
}
```

### Responses

#### 200: The new price list.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | | Slug. Length: min 1, max 64. |
| `name` | string | | Name. Length: min 1, max 128. |
| `currency_code` | string | | ISO 4217 currency code. Length: min 3, max 3. |
| `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`. |
| `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`. |
| `rules` | object[] | | Length: max 5. |
| `rules[].source_price_list_slug` | string | | Source PriceList slug. Length: min 1, max 64. |
| `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. |
| `rules[].adjustment_direction` | "plus" \| "minus" | | Adjustment direction (plus, minus) |
| `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. |

```json
{
  "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
    }
  ]
}
```

#### 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"
}
```