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

Get All Product Variants

GET /catalog/products/{product_id}/variants

Request

Returns a list of product Variants. 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.

  • product_id in path - integer - required

    The ID of the Product to which the resource belongs.

  • 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_fields in query - string

    Fields to include, in a comma-separated list. The ID and the specified fields will be returned.

  • exclude_fields in query - string

    Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.

example

curl --request get \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/products/[product_id]/variants' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx' \
  --data '{}'

Response

Body

object | application/json

  • data    array[object]

  • meta    object

    Data about the response, including pagination and collection totals.

example

{
  "data": [
    {
      "id": 382,
      "product_id": 192,
      "sku": "SMIT",
      "sku_id": 348,
      "price": 10,
      "calculated_price": 10,
      "sale_price": 8,
      "retail_price": 10,
      "map_price": {},
      "weight": 4,
      "calculated_weight": 2,
      "width": 5,
      "height": 5,
      "depth": 5,
      "is_free_shipping": false,
      "fixed_cost_shipping_price": 10,
      "purchasing_disabled": false,
      "purchasing_disabled_message": "",
      "image_url": "",
      "cost_price": 0,
      "upc": "",
      "mpn": "",
      "gtin": "",
      "inventory_level": 0,
      "inventory_warning_level": 0,
      "bin_picking_number": "",
      "option_values": [
        {
          "id": 174,
          "label": "Beige",
          "option_id": 220,
          "option_display_name": "Color"
        }
      ]
    },
    {
      "id": 383,
      "product_id": 192,
      "sku": "SMIT-1",
      "sku_id": 349,
      "price": 25,
      "calculated_price": 25,
      "sale_price": 20,
      "retail_price": 25,
      "map_price": {},
      "weight": 2,
      "calculated_weight": 1,
      "width": 5,
      "height": 5,
      "depth": 5,
      "is_free_shipping": false,
      "fixed_cost_shipping_price": 10,
      "purchasing_disabled": false,
      "purchasing_disabled_message": "",
      "image_url": "",
      "cost_price": 25,
      "upc": "",
      "mpn": "",
      "gtin": "",
      "inventory_level": 0,
      "inventory_warning_level": 0,
      "bin_picking_number": "",
      "option_values": [
        {
          "id": 175,
          "label": "Grey",
          "option_id": 220,
          "option_display_name": "Color"
        }
      ]
    },
    {
      "id": 384,
      "product_id": 192,
      "sku": "SMIT-2",
      "sku_id": 350,
      "price": 25,
      "calculated_price": 25,
      "sale_price": 20,
      "retail_price": 25,
      "map_price": {},
      "weight": 2,
      "calculated_weight": 1,
      "width": 5,
      "height": 5,
      "depth": 5,
      "is_free_shipping": false,
      "fixed_cost_shipping_price": 10,
      "purchasing_disabled": false,
      "purchasing_disabled_message": "",
      "image_url": "",
      "cost_price": 25,
      "upc": "",
      "mpn": "",
      "gtin": "",
      "inventory_level": 0,
      "inventory_warning_level": 0,
      "bin_picking_number": "",
      "option_values": [
        {
          "id": 176,
          "label": "Black",
          "option_id": 220,
          "option_display_name": "Color"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 3,
      "count": 3,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": {
        "current": "?page=1&limit=50"
      }
    }
  }
}

Create a Product Variant

POST /catalog/products/{product_id}/variants

Request

Creates a Product Variant.

Required Fields

  • sku
  • option_values

Read-Only Fields

  • id

Limits

  • 600 SKUs per product limit.
  • 255 characters SKU length limit.

Variants need to be created one at a time using this endpoint. To use a variant array and create products and variants in the same call use the Create Products during the initial product creation.

Authentication

  • X-Auth-Token in header - required

Parameters

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

    The MIME type of the request body.

Body

application/json

The model for a POST to create variants on a product.

  • cost_price    number

    The cost price of the variant. Not affected by Price List prices.

  • price    number

    This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s default price (set in the Product resource’s price field) will be used as the base price.

  • sale_price    number

    This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s price field) will be used as the sale price.

  • retail_price    number

    This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s price field) will be used as the retail price.

  • weight    number

    This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.

  • width    number

    Width of the variant, which can be used when calculating shipping costs. If this value is null, the product's default width (set in the Product resource's width field) will be used as the base width.

  • height    number

    Height of the variant, which can be used when calculating shipping costs. If this value is null, the product's default height (set in the Product resource's height field) will be used as the base height.

  • depth    number

    Depth of the variant, which can be used when calculating shipping costs. If this value is null, the product's default depth (set in the Product resource's depth field) will be used as the base depth.

  • is_free_shipping    boolean

    Flag used to indicate whether the variant has free shipping. If true, the shipping cost for the variant will be zero.

  • fixed_cost_shipping_price    number

    A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation.

  • purchasing_disabled    boolean

    If true, this variant will not be purchasable on the storefront.

  • purchasing_disabled_message    string

    If purchasing_disabled is true, this message should show on the storefront when the variant is selected.

    >= 0 characters<= 255 characters

  • upc    string

    The UPC code used in feeds for shopping comparison sites and external channel integrations.

  • inventory_level    integer

    Inventory level for the variant, which is used when the product’s inventory_tracking is set to variant.

  • inventory_warning_level    integer

    When the variant hits this inventory level, it is considered low stock.

  • bin_picking_number    string

    Identifies where in a warehouse the variant is located.

    >= 0 characters<= 255 characters

  • image_url    string

    Publicly available image url

  • gtin    string

    Global Trade Item Number

    Example: 012345678905

  • mpn    string

    Manufacturer Part Number

    Example: HV-HM02

  • product_id    integer

  • sku    string

    >= 1 characters<= 255 characters

  • option_values    array[object]

    Array of option and option values IDs that make up this variant. Will be empty if the variant is the product's base variant.

    example

    {
  "cost_price": 0,
  "price": 0,
  "sale_price": 0,
  "retail_price": 0,
  "weight": 0,
  "width": 0,
  "height": 0,
  "depth": 0,
  "is_free_shipping": true,
  "fixed_cost_shipping_price": 0,
  "purchasing_disabled": true,
  "purchasing_disabled_message": "string",
  "upc": "string",
  "inventory_level": 0,
  "inventory_warning_level": 0,
  "bin_picking_number": "string",
  "image_url": "string",
  "gtin": "012345678905",
  "mpn": "HV-HM02",
  "product_id": 0,
  "sku": "string",
  "option_values": [
    {
      "option_display_name": "Color",
      "label": "Beige",
      "id": 146,
      "option_id": 151
    }
  ]
}

    Response

    Body

    object | application/json

    • data

    • meta      object

      Response metadata.

    example-1

    {
  "data": {
    "cost_price": 0,
    "price": 0,
    "sale_price": 0,
    "retail_price": 0,
    "weight": 0,
    "width": 0,
    "height": 0,
    "depth": 0,
    "is_free_shipping": true,
    "fixed_cost_shipping_price": 0,
    "purchasing_disabled": true,
    "purchasing_disabled_message": "string",
    "upc": "string",
    "inventory_level": 0,
    "inventory_warning_level": 0,
    "bin_picking_number": "string",
    "mpn": "string",
    "gtin": "012345678905",
    "id": 0,
    "product_id": 0,
    "sku": "string",
    "sku_id": 0,
    "option_values": [
      {
        "option_display_name": "Color",
        "label": "Beige",
        "id": 146,
        "option_id": 151
      }
    ],
    "calculated_price": 0,
    "calculated_weight": 0
  },
  "meta": {}
}

    example-2

    {
  "data": {
    "id": 384,
    "product_id": 192,
    "sku": "SMIT-2",
    "sku_id": 350,
    "price": 25,
    "calculated_price": 25,
    "sale_price": 20,
    "retail_price": 25,
    "map_price": {},
    "weight": 2,
    "calculated_weight": 1,
    "width": 5,
    "height": 5,
    "depth": 5,
    "is_free_shipping": false,
    "fixed_cost_shipping_price": 10,
    "purchasing_disabled": false,
    "purchasing_disabled_message": "",
    "image_url": "",
    "cost_price": 25,
    "upc": "",
    "mpn": "",
    "gtin": "",
    "inventory_level": 0,
    "inventory_warning_level": 0,
    "bin_picking_number": "",
    "option_values": [
      {
        "id": 176,
        "label": "Black",
        "option_id": 220,
        "option_display_name": "Color"
      }
    ]
  },
  "meta": {}
}

    Get a Product Variant

    GET /catalog/products/{product_id}/variants/{variant_id}

    Request

    Returns a single product Variant. 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.

    • product_id in path - integer - required

      The ID of the Product to which the resource belongs.

    • variant_id in path - integer - required

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

    • variant_id in path - integer - required

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

    • include_fields in query - string

      Fields to include, in a comma-separated list. The ID and the specified fields will be returned.

    • exclude_fields in query - string

      Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.

    example

    curl --request get \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/products/[product_id]/variants/[variant_id]' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx' \
  --data '{}'

    Response

    Body

    object | application/json

    • data

    • meta      object

      Response metadata.

    example

    {
  "data": {
    "id": 384,
    "product_id": 192,
    "sku": "SMIT-2",
    "sku_id": 350,
    "price": 25,
    "calculated_price": 25,
    "sale_price": 20,
    "retail_price": 25,
    "map_price": {},
    "weight": 2,
    "calculated_weight": 1,
    "width": 5,
    "height": 5,
    "depth": 5,
    "is_free_shipping": false,
    "fixed_cost_shipping_price": 10,
    "purchasing_disabled": false,
    "purchasing_disabled_message": "",
    "image_url": "",
    "cost_price": 25,
    "upc": "",
    "mpn": "",
    "gtin": "",
    "inventory_level": 0,
    "inventory_warning_level": 0,
    "bin_picking_number": "",
    "option_values": [
      {
        "id": 176,
        "label": "Black",
        "option_id": 220,
        "option_display_name": "Color"
      }
    ]
  },
  "meta": {}
}

    Update a Product Variant

    PUT /catalog/products/{product_id}/variants/{variant_id}

    Request

    Updates a product Variant.

    Authentication

    • X-Auth-Token in header - required

    Parameters

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

      The MIME type of the request body.

    • variant_id in path - integer - required

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

    Body

    application/json

    The model for a PUT to update variants on a product.

    • cost_price      number

      The cost price of the variant. Not affected by Price List prices.

    • price      number

      This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s default price (set in the Product resource’s price field) will be used as the base price.

    • sale_price      number

      This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s price field) will be used as the sale price.

    • retail_price      number

      This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s price field) will be used as the retail price.

    • weight      number

      This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.

    • width      number

      Width of the variant, which can be used when calculating shipping costs. If this value is null, the product's default width (set in the Product resource's width field) will be used as the base width.

    • height      number

      Height of the variant, which can be used when calculating shipping costs. If this value is null, the product's default height (set in the Product resource's height field) will be used as the base height.

    • depth      number

      Depth of the variant, which can be used when calculating shipping costs. If this value is null, the product's default depth (set in the Product resource's depth field) will be used as the base depth.

    • is_free_shipping      boolean

      Flag used to indicate whether the variant has free shipping. If true, the shipping cost for the variant will be zero.

    • fixed_cost_shipping_price      number

      A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation.

    • purchasing_disabled      boolean

      If true, this variant will not be purchasable on the storefront.

    • purchasing_disabled_message      string

      If purchasing_disabled is true, this message should show on the storefront when the variant is selected.

      >= 0 characters<= 255 characters

    • upc      string

      The UPC code used in feeds for shopping comparison sites and external channel integrations.

    • inventory_level      integer

      Inventory level for the variant, which is used when the product’s inventory_tracking is set to variant.

    • inventory_warning_level      integer

      When the variant hits this inventory level, it is considered low stock.

    • bin_picking_number      string

      Identifies where in a warehouse the variant is located.

      >= 0 characters<= 255 characters

    • mpn      string

      The Manufacturer Part Number (MPN) for the variant.

    • gtin      string

      Example: 012345678905

    • product_id      integer

    • sku      string

      >= 1 characters<= 255 characters

      example

      {
  "cost_price": 0,
  "price": 0,
  "sale_price": 0,
  "retail_price": 0,
  "weight": 0,
  "width": 0,
  "height": 0,
  "depth": 0,
  "is_free_shipping": true,
  "fixed_cost_shipping_price": 0,
  "purchasing_disabled": true,
  "purchasing_disabled_message": "string",
  "upc": "string",
  "inventory_level": 0,
  "inventory_warning_level": 0,
  "bin_picking_number": "string",
  "mpn": "string",
  "gtin": "012345678905",
  "product_id": 0,
  "sku": "string"
}

      Response

      Body

      object | application/json

      • data

      • meta        object

        Response metadata.

      example

      {
  "data": {
    "bin_picking_number": "0",
    "calculated_price": 85,
    "calculated_weight": 1,
    "cost_price": 0,
    "depth": 22,
    "fixed_cost_shipping_price": 0,
    "gtin": "",
    "height": 14.6,
    "id": 65,
    "inventory_level": 0,
    "inventory_warning_level": 0,
    "is_free_shipping": false,
    "map_price": 0,
    "mpn": "TR-SML02",
    "option_values": [],
    "price": 89,
    "product_id": 81,
    "purchasing_disabled": true,
    "purchasing_disabled_message": "This item is not available.",
    "retail_price": 89,
    "sale_price": 85,
    "sku": "OTS",
    "sku_id": 10,
    "upc": "",
    "weight": 1,
    "width": 2
  },
  "meta": {}
}

      Delete a Product Variant

      DELETE /catalog/products/{product_id}/variants/{variant_id}

      Request

      Deletes a product Variant.

      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.

      • product_id in path - integer - required

        The ID of the Product to which the resource belongs.

      • variant_id in path - integer - required

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

      • variant_id in path - integer - required

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

      example

      curl --request delete \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/products/[product_id]/variants/[variant_id]' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx' \
  --data '{}'

      Response

      Create a Variant Image

      POST /catalog/products/{product_id}/variants/{variant_id}/image

      Request

      Creates a Variant Image.

      The image will show on the storefront when the value is selected.

      Required Fields

      • image_file: Form posts. Files larger than 1 MB are not accepted
      • image_url: Any publicly available URL

      Authentication

      • X-Auth-Token in header - required

      Parameters

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

        The MIME type of the request body.

      • variant_id in path - integer - required

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

      Body

      object | application/json

      An object containing a publicly accessible image URL, or a form post that contains an image file.

      • image_url        string

        A public URL for a GIF, JPEG, or PNG image. Limit of 8MB per file.

      example

      {
  "image_url": "string"
}

      Response

      image_url is returned for both image_file and image_url.

      Body

      object | application/json

      Image Response returns for:

      • Create Variant Image
      • Create Modifier Image
      • Create Category Image
      • Create Brand Image

      • data        object

        An object containing a publicly accessible image URL, or a form post that contains an image file.

      • meta        object

        Response metadata.

      example

      {
  "data": {
    "image_url": "https://cdn8.bigcommerce.com/s-id30h7ohwf/product_images/attribute_rule_images/85_source_1536863430.png"
  },
  "meta": {}
}