{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/bigcommerce/main/json-schema/bigcommerce-product-variant-post-schema.json",
  "title": "productVariant_Post",
  "description": "The model for a POST to create variants on a product.\n",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/bigcommerce-product-variants-api-openapi.yml#/components/schemas/productVariant_Post",
  "allOf": [
    {
      "title": "Variant Base",
      "type": "object",
      "properties": {
        "cost_price": {
          "minimum": 0,
          "type": [
            "number",
            "null"
          ],
          "description": "The cost price of the variant. Not affected by Price List prices.",
          "format": "double"
        },
        "price": {
          "minimum": 0,
          "type": [
            "number",
            "null"
          ],
          "description": "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.",
          "format": "double"
        },
        "sale_price": {
          "minimum": 0,
          "type": [
            "number",
            "null"
          ],
          "description": "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.",
          "format": "double"
        },
        "retail_price": {
          "minimum": 0,
          "type": [
            "number",
            "null"
          ],
          "description": "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.",
          "format": "double"
        },
        "weight": {
          "minimum": 0,
          "type": [
            "number",
            "null"
          ],
          "description": "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.",
          "format": "double"
        },
        "width": {
          "minimum": 0,
          "type": [
            "number",
            "null"
          ],
          "description": "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.\n",
          "format": "double"
        },
        "height": {
          "minimum": 0,
          "type": [
            "number",
            "null"
          ],
          "description": "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.\n",
          "format": "double"
        },
        "depth": {
          "minimum": 0,
          "type": [
            "number",
            "null"
          ],
          "description": "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.\n",
          "format": "double"
        },
        "is_free_shipping": {
          "type": "boolean",
          "description": "Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero.\n"
        },
        "fixed_cost_shipping_price": {
          "minimum": 0,
          "type": [
            "number",
            "null"
          ],
          "description": "A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation.\n",
          "format": "double"
        },
        "purchasing_disabled": {
          "type": "boolean",
          "description": "If `true`, this variant will not be purchasable on the storefront."
        },
        "purchasing_disabled_message": {
          "maxLength": 255,
          "minLength": 0,
          "type": "string",
          "description": "If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected."
        },
        "upc": {
          "type": [
            "string",
            "null"
          ],
          "description": "The UPC code used in feeds for shopping comparison sites and external channel integrations."
        },
        "inventory_level": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`. The Catalog API returns the inventory for only the default location.\n\nThe inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories, or the total inventory for a product, cannot exceed 2,147,483,647. \n\nIf you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit.\n\nThe Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). ",
          "maximum": 2147483647
        },
        "inventory_warning_level": {
          "type": [
            "integer",
            "null"
          ],
          "description": "When the variant hits this inventory level, it is considered low stock.",
          "maximum": 2147483647
        },
        "bin_picking_number": {
          "maxLength": 255,
          "minLength": 0,
          "type": [
            "string",
            "null"
          ],
          "description": "Identifies where in a warehouse the variant is located."
        },
        "image_url": {
          "type": "string",
          "description": "Publicly available image url"
        },
        "gtin": {
          "type": "string",
          "description": "Global Trade Item Number"
        },
        "mpn": {
          "type": "string",
          "description": "Manufacturer Part Number"
        }
      },
      "description": "Common Variant properties."
    },
    {
      "type": "object",
      "properties": {
        "product_id": {
          "type": "integer",
          "x-required": [
            "post"
          ]
        },
        "sku": {
          "maxLength": 255,
          "minLength": 1,
          "type": "string",
          "x-required": [
            "post"
          ]
        },
        "option_values": {
          "type": "array",
          "description": "Array of option and option values IDs that make up this variant. Will be empty if the variant is the productʼs base variant.",
          "items": {
            "$ref": "#/$defs/productVariantOptionValue_Full"
          },
          "x-required": [
            "post"
          ]
        }
      }
    }
  ],
  "x-internal": false,
  "$defs": {
    "productVariantOptionValue_Base": {
      "title": "productVariantOptionValue_Base",
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "description": "`option_value` ID."
        },
        "option_id": {
          "type": "integer",
          "description": "`option` ID."
        }
      },
      "description": "Common Product Variant Option properties.",
      "x-internal": false
    },
    "productVariantOptionValue_Full": {
      "title": "productVariantOptionValue_Full",
      "allOf": [
        {
          "type": "object",
          "properties": {
            "option_display_name": {
              "maxLength": 255,
              "minLength": 1,
              "type": "string",
              "description": "The name of the option.\n",
              "x-required": [
                "post"
              ]
            },
            "label": {
              "maxLength": 255,
              "minLength": 1,
              "type": "string",
              "description": "The label of the option value.\n",
              "x-required": [
                "post"
              ]
            }
          }
        },
        {
          "$ref": "#/$defs/productVariantOptionValue_Base"
        }
      ],
      "x-internal": false
    }
  }
}