PUT
Edit a product variant
Company space For: Manager · Permission: product_variants.update Conditions
  • image_id must be an image of the same product and organization.
  • Fiscal fields additionally require the permission to update item taxes.
  • Weight, volume and maximum sellable quantity are sent together with their unit; the unit must match the kind of measure or the product’s unit category and the value must be exactly representable in the reference unit.
  • When options are sent, the new combination must not match another variant of the product.
What else happens
  • Sending options replaces all existing options of the variant and recomputes its option signature.
  • Updates the variant’s item (measurements, tax settings); tracking is not changed by this call, it follows the product.
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 owns the variant (27-character KSUID).

variant
string
required

Identifier of the variant to update (27-character KSUID). It must belong to the product.

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.

Body

application/json
weight
integer | null

Weight of one unit, in the unit given by weight_unit_id (an integer greater than zero). Must be sent together with weight_unit_id; send both as null to clear. Must be exactly representable in the reference unit.

weight_unit_id
string | null

Identifier of a measurement unit of the weight category (27-character KSUID). Required when weight is sent.

Required string length: 27
volume
integer | null

Volume of one unit, in the unit given by volume_unit_id (an integer greater than zero). Must be sent together with volume_unit_id; send both as null to clear.

volume_unit_id
string | null

Identifier of a measurement unit of the volume category (27-character KSUID). Required when volume is sent.

Required string length: 27
tax_configuration_mode
enum<string>

inherit takes the tax settings from the product category; custom sets them on the variant and then requires is_taxable. Needs the permission to update item taxes.

Available options:
inherit,
custom
is_taxable
boolean | null

Whether the variant is taxable. Required when the mode is custom. Needs the permission to update item taxes.

vat_rate_id
string | null

Identifier of the VAT rate (27-character KSUID). It must be active and match the company's country and fiscal status.

Required string length: 27
max_sellable_quantity
integer | null

Largest quantity sellable in one line, in the unit given by max_sellable_unit_id (an integer greater than zero). Must be sent together with the unit.

max_sellable_unit_id
string | null

Identifier of a unit of the product's own unit-of-measure category (27-character KSUID). Required when max_sellable_quantity is sent.

Required string length: 27
image_id
string | null

Identifier of one of the product's images to link to this variant. Null or omitted keeps the current image.

options
object[] | null

New complete list of option name and value pairs of the variant; replaces the existing ones. The combination must be unique among the product's variants and option names must be distinct.

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.