Thanks for being patient while we implement your feedback to improve the developer experience.

Get All Price List Records

GET /pricelists/{price_list_id}/records

Request

Returns a list of Price List Records associated with a Price List.

Notes

  • Supports up to 10 simultaneous GET requests. Running more than the allowed number of requests concurrently on the same store will result in a 429 status error and your additional requests will fail.
  • Store Pricelist Records data to reduce the number of calls and maximize performance.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string - required

    The MIME type of the response body.

  • price_list_id in path - integer - required

    The ID of the Price List requested.

  • variant_id:in in query - integer

    The ID of the Variant for which prices were requested.

  • product_id:in in query - string

    A comma-separated list of IDs of Products for which prices were requested.

  • currency in query - string

    Filter items by currency.

  • page in query - integer

    Specifies the page number in a limited (paginated) list of products.

  • limit in query - integer

    Controls the number of items per page in a limited (paginated) list of products.

  • include in query - string

    Sub-resources to include on a price record, in a comma-separated list. Valid expansions currently include bulk_pricing_tiers and sku. Other values will be ignored.

  • price in query - number

    Filter items by price.

  • sale_price in query - number

    Filter items by sale_price.

  • retail_price in query - number

    Filter items by retail_price.

  • map_price in query - number

    Filter items by map_price.

  • calculated_price in query - number

    Filter items by calculated_price.

  • date_created in query - string

    Filter items by date_created.

  • date_modified in query - string

    Filter items by date_modified. For example v3/catalog/products?date_last_imported:min=2022-06-15

  • sku in query - string

    Filter items by SKU.

  • sku:in in query - array
  • currency:in in query - array
  • price:max in query - number
  • price:min in query - number
  • sale_price:max in query - number
  • sale_price:min in query - number
  • retail_price:max in query - number
  • retail_price:min in query - number
  • map_price:max in query - number
  • map_price:min in query - number
  • calculated_price:max in query - number
  • calculated_price:min in query - number
  • date_created:max in query - string
  • date_created:min in query - string
  • date_modified:max in query - string
  • date_modified:min in query - string

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/pricelists/[price_list_id]/records' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

PriceRecord Collection Response returns for:

  • Get All PriceList Records
  • Get PriceList Records by Variant ID

  • data    array[object]

  • meta    object

    Data about the response, including pagination and collection totals.

example

{
  "data": [
    {
      "price_list_id": 3,
      "variant_id": 358,
      "price": 25.48,
      "sale_price": 18.57,
      "retail_price": 25.48,
      "map_price": 18.57,
      "calculated_price": 25.48,
      "date_created": "2022-09-17T20:33:14Z",
      "date_modified": "2022-09-17T20:33:14Z",
      "currency": "usd",
      "product_id": 187,
      "bulk_pricing_tiers": []
    },
    {
      "price_list_id": 3,
      "variant_id": 359,
      "price": 31.31,
      "sale_price": 31.31,
      "retail_price": 31.31,
      "map_price": 31.31,
      "calculated_price": 31.31,
      "date_created": "2022-09-17T20:33:14Z",
      "date_modified": "2022-09-17T20:33:14Z",
      "currency": "usd",
      "product_id": 188,
      "bulk_pricing_tiers": []
    },
    {
      "price_list_id": 3,
      "variant_id": 360,
      "price": 18.57,
      "sale_price": 18.57,
      "retail_price": 18.57,
      "map_price": 18.57,
      "calculated_price": 18.57,
      "date_created": "2022-09-17T20:33:14Z",
      "date_modified": "2022-09-17T20:33:14Z",
      "currency": "usd",
      "product_id": 189,
      "bulk_pricing_tiers": []
    },
    {
      "price_list_id": 3,
      "variant_id": 361,
      "price": 22.54,
      "sale_price": 22.54,
      "retail_price": 22.54,
      "map_price": 22.54,
      "calculated_price": 22.54,
      "date_created": "2022-09-17T20:33:14Z",
      "date_modified": "2022-09-17T20:33:14Z",
      "currency": "usd",
      "product_id": 190,
      "bulk_pricing_tiers": []
    },
    {
      "price_list_id": 3,
      "variant_id": 362,
      "price": 27.39,
      "sale_price": 27.39,
      "retail_price": 27.39,
      "map_price": 27.39,
      "calculated_price": 27.39,
      "date_created": "2022-09-17T20:33:14Z",
      "date_modified": "2022-09-17T20:51:26Z",
      "currency": "usd",
      "product_id": 191,
      "bulk_pricing_tiers": [
        {
          "quantity_min": 10,
          "quantity_max": 19,
          "type": "percent",
          "amount": 1
        },
        {
          "quantity_min": 20,
          "quantity_max": 29,
          "type": "percent",
          "amount": 3
        },
        {
          "quantity_min": 30,
          "quantity_max": 2147483647,
          "type": "percent",
          "amount": 5
        }
      ]
    },
    {
      "price_list_id": 3,
      "variant_id": 382,
      "price": 9.8,
      "sale_price": 9.8,
      "retail_price": 9.8,
      "map_price": 9.8,
      "calculated_price": 9.8,
      "date_created": "2022-09-17T20:33:14Z",
      "date_modified": "2022-09-17T20:33:14Z",
      "currency": "usd",
      "product_id": 192,
      "bulk_pricing_tiers": []
    },
    {
      "price_list_id": 3,
      "variant_id": 383,
      "price": 24.5,
      "sale_price": 24.5,
      "retail_price": 24.5,
      "map_price": 24.5,
      "calculated_price": 24.5,
      "date_created": "2022-09-17T20:33:14Z",
      "date_modified": "2022-09-17T20:33:14Z",
      "currency": "usd",
      "product_id": 192,
      "bulk_pricing_tiers": []
    },
    {
      "price_list_id": 3,
      "variant_id": 384,
      "price": 24.5,
      "sale_price": 24.5,
      "retail_price": 24.5,
      "map_price": 24.5,
      "calculated_price": 24.5,
      "date_created": "2022-09-17T20:33:14Z",
      "date_modified": "2022-09-17T20:33:14Z",
      "currency": "usd",
      "product_id": 192,
      "bulk_pricing_tiers": []
    },
    {
      "price_list_id": 3,
      "variant_id": 385,
      "price": 9.8,
      "sale_price": 9.8,
      "retail_price": 9.8,
      "map_price": 9.8,
      "calculated_price": 9.8,
      "date_created": "2022-09-17T20:33:14Z",
      "date_modified": "2022-09-17T20:33:14Z",
      "currency": "usd",
      "product_id": 193,
      "bulk_pricing_tiers": []
    },
    {
      "price_list_id": 3,
      "variant_id": 386,
      "price": 10.78,
      "sale_price": 10.78,
      "retail_price": 10.78,
      "map_price": 10.78,
      "calculated_price": 10.78,
      "date_created": "2022-09-17T20:33:14Z",
      "date_modified": "2022-09-17T20:33:14Z",
      "currency": "usd",
      "product_id": 194,
      "bulk_pricing_tiers": []
    },
    {
      "price_list_id": 3,
      "variant_id": 388,
      "price": 10.78,
      "sale_price": 10.78,
      "retail_price": 10.78,
      "map_price": 10.78,
      "calculated_price": 10.78,
      "date_created": "2022-09-17T20:33:14Z",
      "date_modified": "2022-09-17T20:35:42Z",
      "currency": "usd",
      "product_id": 195,
      "bulk_pricing_tiers": [
        {
          "quantity_min": 2,
          "quantity_max": 9,
          "type": "percent",
          "amount": 1
        },
        {
          "quantity_min": 10,
          "quantity_max": 19,
          "type": "percent",
          "amount": 2
        },
        {
          "quantity_min": 20,
          "quantity_max": 2147483647,
          "type": "percent",
          "amount": 3
        }
      ]
    },
    {
      "price_list_id": 3,
      "variant_id": 389,
      "price": 18.62,
      "sale_price": 18.62,
      "retail_price": 18.62,
      "map_price": 18.62,
      "calculated_price": 18.62,
      "date_created": "2022-09-17T20:33:14Z",
      "date_modified": "2022-09-17T20:35:42Z",
      "currency": "usd",
      "product_id": 195,
      "bulk_pricing_tiers": [
        {
          "quantity_min": 2,
          "quantity_max": 9,
          "type": "percent",
          "amount": 1
        },
        {
          "quantity_min": 10,
          "quantity_max": 19,
          "type": "percent",
          "amount": 2
        },
        {
          "quantity_min": 20,
          "quantity_max": 2147483647,
          "type": "percent",
          "amount": 3
        }
      ]
    },
    {
      "price_list_id": 3,
      "variant_id": 390,
      "price": 10.78,
      "sale_price": 10.78,
      "retail_price": 10.78,
      "map_price": 10.78,
      "calculated_price": 10.78,
      "date_created": "2022-09-17T20:33:14Z",
      "date_modified": "2022-09-17T20:35:42Z",
      "currency": "usd",
      "product_id": 195,
      "bulk_pricing_tiers": [
        {
          "quantity_min": 2,
          "quantity_max": 9,
          "type": "percent",
          "amount": 1
        },
        {
          "quantity_min": 10,
          "quantity_max": 19,
          "type": "percent",
          "amount": 2
        },
        {
          "quantity_min": 20,
          "quantity_max": 2147483647,
          "type": "percent",
          "amount": 3
        }
      ]
    },
    {
      "price_list_id": 3,
      "variant_id": 391,
      "price": 10.78,
      "sale_price": 10.78,
      "retail_price": 10.78,
      "map_price": 10.78,
      "calculated_price": 10.78,
      "date_created": "2022-09-17T20:33:14Z",
      "date_modified": "2022-09-17T20:35:42Z",
      "currency": "usd",
      "product_id": 195,
      "bulk_pricing_tiers": [
        {
          "quantity_min": 2,
          "quantity_max": 9,
          "type": "percent",
          "amount": 1
        },
        {
          "quantity_min": 10,
          "quantity_max": 19,
          "type": "percent",
          "amount": 2
        },
        {
          "quantity_min": 20,
          "quantity_max": 2147483647,
          "type": "percent",
          "amount": 3
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 14,
      "count": 14,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1
    }
  }
}

Upsert Price List Records

PUT /pricelists/{price_list_id}/records

Request

Creates or updates Price List Records.

Required Fields

  • currency

Notes

  • Batch updates are supported by this endpoint, meaning that several price objects can be updated in one request. This allows you to do the same work as many individual requests to singleton endpoints
  • Batch requests support up to 1,000 items per request.
  • Up to 2 concurrent batch upsert requests are supported with this API. Running more than the allowed concurrent requests in parallel on the same store will cause a 429 error and your additional requests will fail. You are encouraged to run requests sequentially with as many records per request as possible, in order to maximize performance.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • price_list_id in path - integer - required

    The ID of the Price List requested.

  • X-Strict-Mode in header - integer

    Header that determines whether the Batch API operates in strict mode or not. Strict mode will reject the entire request if any item in the batch has an error.

  • Content-Type in header with default of application/json - string - required

    The MIME type of the request body.

Body

array | application/json

  • variant_id    integer

    The variant ID with which this price set is associated. Either variant_id or SKU is required.

    Example: 331

  • sku    string

    The SKU for the variant with which this price set is associated. Either SKU or variant_id is required.

    Example: SMB-123

  • currency    string

    The 3-letter currency code with which this price set is associated.

    Example: usd

  • price    number

    The list price for the variant mapped in a Price List. Overrides any existing or Catalog list price for the variant/product.

    Example: 3.99

  • sale_price    number

    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.

    Example: 3.49

  • retail_price    number

    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.

    Example: 4.99

  • map_price    number

    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.

    Example: 2.5

  • bulk_pricing_tiers    array[object]

  • sku    string

    The SKU code associated with this Price Record if requested and it exists.

    Example: SMB-123

    example

    {}

    Response

    Success response for batch PUT requests of Price Records.

    Body

    object | application/json

    • data      object

    • meta      object

    example

    {
  "data": {},
  "meta": {}
}

    Delete a Price List Record

    DELETE /pricelists/{price_list_id}/records

    Request

    Deletes a Price List Record. Deleting the records does not delete the Price List. Optional parameters can be passed in.

    Authentication

    • X-Auth-Token in header - required

    Parameters

    • store_hash in path - string
    • Accept in header with default of application/json - string - required

      The MIME type of the response body.

    • price_list_id in path - integer - required

      The ID of the Price List requested.

    • variant_id:in in query - integer

      The ID of the Variant for which prices were requested.

    example

    curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/pricelists/[price_list_id]/records' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

    Response

    Body

    object | application/json

    No-content response for the BigCommerce API.

    • status      integer

      204 HTTP status code.

    • title      string

      The error title describing the situation.

    • type      string

    • instance      string

    example

    {
  "status": 0,
  "title": "string",
  "type": "string",
  "instance": "string"
}

    Get Price Records by Variant

    GET /pricelists/{price_list_id}/records/{variant_id}

    Request

    Returns Price List Records using the variant ID. Will also contain currency records.

    Notes

    • Supports up to 40 simultaneous GET requests. Running more than the allowed number of requests concurrently on the same store will result in a 429 status error, and your additional requests will fail.
    • Store Pricelist Records data to reduce the number of calls and maximize performance.

    Authentication

    • X-Auth-Token in header - required

    Parameters

    • store_hash in path - string
    • Accept in header with default of application/json - string - required

      The MIME type of the response body.

    • price_list_id in path - integer - required

      The ID of the Price List requested.

    • variant_id in path - integer - required

      ID of the variant on a product, or on an associated Price List Record.

    example

    curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/pricelists/[price_list_id]/records/[variant_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

    Response

    Body

    object | application/json

    PriceRecord Collection Response returns for:

    • Get All PriceList Records
    • Get PriceList Records by Variant ID

    • data      array[object]

    • meta      object

      Data related to the response, including pagination and collection totals.

    example

    {
  "data": [
    {
      "calculated_price": 24.64,
      "date_created": "2022-08-23T19:59:23Z",
      "date_modified": "2022-08-23T19:59:23Z",
      "product_id": 158,
      "price_list_id": 2,
      "variant_id": 325,
      "sku": "SMB-123",
      "currency": "usd",
      "price": 3.99,
      "sale_price": 5.99,
      "retail_price": 6.99,
      "map_price": 5.99,
      "bulk_pricing_tiers": [
        {
          "quantity_min": 1,
          "quantity_max": 10,
          "type": "price",
          "amount": 3
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 36,
      "count": 36,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": {
        "previous": "string",
        "current": "?page=1&limit=50",
        "next": "string"
      }
    }
  }
}

    Get a Price Record by Currency Code

    GET /pricelists/{price_list_id}/records/{variant_id}/{currency_code}

    Request

    Returns a Price List Record using the currency code. You can use optional parameters.

    Notes

    • Supports up to 40 simultaneous GET requests. Running more than the allowed number of requests concurrently on the same store will result in a 429 status error, and your additional requests will fail.

    Authentication

    • X-Auth-Token in header - required

    Parameters

    • store_hash in path - string
    • Accept in header with default of application/json - string - required

      The MIME type of the response body.

    • price_list_id in path - integer - required

      The ID of the Price List requested.

    • variant_id in path - integer - required

      ID of the variant on a product, or on an associated Price List Record.

    • currency_code in path - string - required

      The currency code associated with the price record being acted upon.

    • include in query - string

      Sub-resources to include on a price record, in a comma-separated list. Valid expansions currently include bulk_pricing_tiers and sku. Other valies will be ignored.

    example

    curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/pricelists/[price_list_id]/records/[variant_id]/[currency_code]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

    Response

    Body

    object | application/json

    Response payload for the BigCommerce API.

    • data      object

      The Price Record object.

    • meta      object

      Response metadata.

    example

    {
  "data": {
    "price_list_id": 4,
    "variant_id": 356,
    "price": 22.544,
    "sale_price": 22.544,
    "retail_price": 22.544,
    "map_price": 22.544,
    "calculated_price": 22.544,
    "date_created": "2022-09-18T13:18:15Z",
    "date_modified": "2022-09-18T13:18:15Z",
    "currency": "eur",
    "product_id": 185
  },
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1
    }
  }
}

    Set Price List Record by Currency Code

    PUT /pricelists/{price_list_id}/records/{variant_id}/{currency_code}

    Request

    Creates or updates a Price List Record using the currency code.

    Notes

    • Supports up to 40 simultaneous PUT requests. Running more than the allowed number of requests concurrently on the same store will result in a 429 status error, and your additional requests will fail.

    Authentication

    • X-Auth-Token in header - required

    Parameters

    • store_hash in path - string
    • price_list_id in path - integer - required

      The ID of the Price List requested.

    • variant_id in path - integer - required

      ID of the variant on a product, or on an associated Price List Record.

    • currency_code in path - string - required

      The currency code associated with the price record being acted upon.

    • Content-Type in header with default of application/json - string - required

      The MIME type of the request body.

    Body

    application/json

    • price      number

      The list price for the variant mapped in a Price List. Overrides any existing or Catalog list price for the variant/product.

      Example: 3.99

    • sale_price      number

      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      number

      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      number

      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      array[object]

    • sku      string

      The SKU code associated with this Price Record if requested and it exists.

      Example: SMB-123

      example

      {
  "price": 3.99,
  "sale_price": 0,
  "retail_price": 0,
  "map_price": 0,
  "bulk_pricing_tiers": [
    {
      "quantity_min": 1,
      "quantity_max": 10,
      "type": "price",
      "amount": 3
    }
  ],
  "sku": "SMB-123"
}

      Response

      Body

      object | application/json

      Response payload for the BigCommerce API.

      • data        object

        The Price Record object.

      • meta        object

        Response metadata.

      value

      {
  "data": {
    "price_list_id": 4,
    "variant_id": 356,
    "price": 12.99,
    "sale_price": 10.99,
    "retail_price": 15.99,
    "map_price": 17.99,
    "calculated_price": 10.99,
    "date_created": "2022-09-18T13:18:15Z",
    "date_modified": "2022-09-18T13:30:48Z",
    "currency": "eur",
    "product_id": 185,
    "bulk_pricing_tiers": [
      {
        "quantity_min": 5,
        "quantity_max": 10,
        "type": "percent",
        "amount": 1
      },
      {
        "quantity_min": 11,
        "quantity_max": 20,
        "type": "percent",
        "amount": 2
      }
    ]
  },
  "meta": {}
}

      Delete a Price Record by Currency Code

      DELETE /pricelists/{price_list_id}/records/{variant_id}/{currency_code}

      Request

      Deletes a Price List Record using the currency code.

      Authentication

      • X-Auth-Token in header - required

      Parameters

      • store_hash in path - string
      • Accept in header with default of application/json - string - required

        The MIME type of the response body.

      • price_list_id in path - integer - required

        The ID of the Price List requested.

      • variant_id in path - integer - required

        ID of the variant on a product, or on an associated Price List Record.

      • currency_code in path - string - required

        The currency code associated with the price record being acted upon.

      example

      curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/pricelists/[price_list_id]/records/[variant_id]/[currency_code]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

      Response