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

# Create or Update Batch of Price Lists Records

PUT https://api.bigcommerce.com/stores/{store_hash}/v3/pricelists/records
Content-Type: application/json

Creates or updates a batch of `Price Lists Records`; may include price list records from more than one price list. Concurrency limit of 1. It is advised to use POST to get better performance when creating price records.

Each request must include `price_list_id` and `currency`, plus either `variant_id` or `sku` to identify the variant.

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

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

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

### Body (application/json)

This endpoint expects a list of PriceRecordBatchItem.

- `list of PriceRecordBatchItem`

## Response

### 200

Success response for batch PUT of `Price List Records`.

- `data` (SuccessBatchResponseData, optional)
- `meta` (SuccessBatchResponseMeta, optional)

## Errors

### 422 Unprocessable Entity Error

Error response for batch PUT of `Price Records`. May include errors during partial update in non-strict mode.

- `data` (PriceRecordIdentifiers, optional) — The `Price Record` object used in batch create or update.
- `field_errors` (DetailedErrors, optional)

## Types

### PriceRecordBatchItem

Common Price Record properties.

- `price_list_id` (integer, required) — The price list ID the price record is associated with.
- `currency` (string, required) — The 3-letter country code with which this price record is associated.
- `variant_id` (integer, optional) — The variant with which the price record is associated. Either `variant_id` or `sku` is required.
- `sku` (string, optional) — The SKU for the variant with which this price record is associated. Either `sku` or `variant_id` is required.
- `price` (double, optional) — The list price for the variant mapped in a Price List. Overrides any existing or Catalog list price for the variant/product. If empty, the sale price will be treated as not being set on this variant.
- `sale_price` (double, optional) — The sale price for the variant mapped in a Price List. Overrides any existing or Catalog sale price for the variant/product. If empty, the sale price will be treated as not being set on this variant.
- `retail_price` (double, optional) — The retail price for the variant mapped in a Price List. Overrides any existing or Catalog retail price for the variant/product. If empty, the retail price will be treated as not being set on this variant.
- `map_price` (double, optional) — The MAP (Minimum Advertised Price) for the variant mapped in a Price List. Overrides any existing or Catalog MAP price for the variant/product. If empty, the `map_ price` will be treated as not being set on this variant.
- `bulk_pricing_tiers` (list of BulkPricingTier, optional)

### SuccessBatchResponseData

### SuccessBatchResponseMeta

### PriceRecordIdentifiers

The `Price Record` object used in batch create or update.

- `price_list_id` (integer, optional) — The Price List with which this price record is associated.
- `variant_id` (integer, optional) — The variant with which this price record is associated. Either `variant_id` or `sku` is required.
- `sku` (string, optional) — The variant with which this price record is associated. Either `sku` or `variant_id` is required.
- `currency` (string, optional) — The 3-letter currency code with which this price set is associated.

### DetailedErrors

### BulkPricingTier

- `quantity_min` (integer, optional) — The cart's minimum quantity of associated variants needed to qualify for this tier's pricing.
- `quantity_max` (integer, optional) — The cart's maximum allowed quantity of associated variants to qualify for this tier's pricing.
- `type` (enum, optional) — The type of adjustment that is made. Acceptable values: * price – the adjustment amount per product * percent – the adjustment as a percentage of the original price * fixed – the adjusted absolute price of the product
  - Allowed values: `fixed`, `price`, `percent`
- `amount` (double, optional) — The price adjustment amount. This value and the type will decide the price per variant for the pricing tier.

## Examples

**Request**

```json
[
  {
    "price_list_id": 1,
    "currency": "usd",
    "variant_id": 5
  }
]
```

**Response**

```json
{
  "data": {},
  "meta": {}
}
```

**SDK Code**

```python
import requests

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

payload = [
    {
        "price_list_id": 1,
        "currency": "usd",
        "variant_id": 5
    }
]
headers = {
    "Accept": "application/json",
    "X-Auth-Token": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.bigcommerce.com/stores/store_hash/v3/pricelists/records';
const options = {
  method: 'PUT',
  headers: {
    Accept: 'application/json',
    'X-Auth-Token': '<apiKey>',
    'Content-Type': 'application/json'
  },
  body: '[{"price_list_id":1,"currency":"usd","variant_id":5}]'
};

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"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("[\n  {\n    \"price_list_id\": 1,\n    \"currency\": \"usd\",\n    \"variant_id\": 5\n  }\n]")

	req, _ := http.NewRequest("PUT", url, payload)

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

	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/pricelists/records")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Accept"] = 'application/json'
request["X-Auth-Token"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"price_list_id\": 1,\n    \"currency\": \"usd\",\n    \"variant_id\": 5\n  }\n]"

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

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

HttpResponse<String> response = Unirest.put("https://api.bigcommerce.com/stores/store_hash/v3/pricelists/records")
  .header("Accept", "application/json")
  .header("X-Auth-Token", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"price_list_id\": 1,\n    \"currency\": \"usd\",\n    \"variant_id\": 5\n  }\n]")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.bigcommerce.com/stores/store_hash/v3/pricelists/records', [
  'body' => '[
  {
    "price_list_id": 1,
    "currency": "usd",
    "variant_id": 5
  }
]',
  'headers' => [
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
    'X-Auth-Token' => '<apiKey>',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/pricelists/records");
var request = new RestRequest(Method.PUT);
request.AddHeader("Accept", "application/json");
request.AddHeader("X-Auth-Token", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "[\n  {\n    \"price_list_id\": 1,\n    \"currency\": \"usd\",\n    \"variant_id\": 5\n  }\n]", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "application/json",
  "X-Auth-Token": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  [
    "price_list_id": 1,
    "currency": "usd",
    "variant_id": 5
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v3/pricelists/records")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

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()
```