POST
Add product variants
Company space For: Manager · Permission: product_variants.create, products.update Conditions
  • Both products.update on the product and product_variants.create are needed.
  • Each variant needs at least one unit with at least one price; options must be present (it may be empty).
  • Option combinations must not repeat inside the request nor match an existing variant of the product.
  • SKUs and barcodes must not repeat inside the payload and are unique per organization when set.
  • Fiscal fields (tax_configuration_mode, is_taxable, vat_rate_id) also require the permission to update item taxes.
  • Weight, volume and maximum sellable quantity need their unit and must match the kind of measure or the product’s unit category.
What else happens
  • Creates one item per variant (status draft, tracking copied from the product, purchase nature goods) and a stock record when tracked.
  • Creates options, option values, variants, units of sale and prices; all in one transaction.
Part of Create products and variants.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

product
string
required

Identifier of the product that receives the variants (27-character KSUID).

Query Parameters

response
enum<string>
default:none

Response mode. Default none; none answers 204 No Content.

Available options:
none,
resource
fields
string

Comma-separated JSON keys of the root resource (id is always rendered). Available: vat_rate_id, tax_configuration_mode, id, stockable_id, title, weight, weight_unit_id, volume, volume_unit_id, is_tracked, is_taxable, max_sellable_quantity, max_sellable_unit_id, created_at, updated_at, options, organization_id.

include
string

Comma-separated include paths, each optionally followed by its fields in parentheses: units(id,sku),units.uomUnit(id,name). Max depth 6, max 40 paths. Available: vat_rate, taxes, image, inventoryItem, inventoryItem.stockable, inventoryItem.inventoryLevels, levels, levels.inventoryItem, levels.asset, levels.stocks, units, units.uomUnit, units.prices, units.stockable.

Response

Resource (only with response=resource).

id

Identifier of the variant (27-character KSUID).

stockable_id

Identifier of the item behind the variant (27-character KSUID).

title

Display title of the variant: the product title followed by its option values.

weight
number | null

Weight of one unit of the variant, expressed in the unit given by weight_unit_id (converted back from the reference unit). Null when not set.

weight_unit_id

Identifier of the weight unit of weight (27-character KSUID), or null.

volume
number | null

Volume of one unit of the variant, expressed in the unit given by volume_unit_id. Null when not set.

volume_unit_id

Identifier of the volume unit of volume (27-character KSUID), or null.

is_tracked
boolean | null

Whether stock is tracked for this variant.

is_taxable
boolean | null

Whether the variant is taxable according to its tax configuration (own or inherited).

max_sellable_quantity
number | null

Largest quantity that can be sold in one line, expressed in the unit given by max_sellable_unit_id. Null when there is no limit.

max_sellable_unit_id

Identifier of the unit of max_sellable_quantity (27-character KSUID), or null.

created_at

Date and time the record was created (ISO 8601, UTC).

updated_at

Date and time the record was last changed (ISO 8601, UTC).

image
object | null

Picture linked to this variant, or null. Present only when requested with include=image.

options
object

Option values of the variant keyed option1, option2, ... in position order, each with name and value.

inventoryItem
object | null

Stock record of the variant, when stock is tracked. Present only when requested with include=inventoryItem.

levels
array

Stock levels of the variant per asset, limited to those the current actor may see. Present only when requested with include=levels.

units
array

Sellable units of the variant with SKU, barcode and prices. Present only when requested with include=units.

organization_id

Identifier of the organization the record belongs to.

vat_rate_id

Identifier of the VAT rate set on the variant, or null (27-character KSUID).

tax_configuration_mode

inherit when the variant takes its tax settings from its product category, custom when they are set on the variant itself.

vat_rate
object | null

VAT rate details. Present only when requested with include=vat_rate.

taxes
array

Taxes applied to the variant. Present only when requested with include=taxes.