ProductVariantsWriteRequest
POST /api/v1/products/{id}/variants body. Up to 100 variants, cents-native. Each row is matched to an existing variant by external_id, then sku (any case), then the exact option_name + option_value pair (plus option2_name + option2_value when the variant has a second axis, e.g. Size x Colour), and updated IN PLACE; unmatched rows are inserted. Nothing is ever deleted. `mode` merge (default) leaves unlisted variants alone; replace deactivates them — except a variant an open order points at, which stays active and keeps its option / SKU / external id (reported in variant_sync.protected / identity_locked; its stock, price and image still update). `stock` is ABSOLUTE, never a delta. Rows may not repeat an external_id, a SKU (any case) or an option pair.
CompanyAPIStubUnknownPlaceholder
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/xavio-in/json-schema/xavio-in-product-variants-write-request-schema.json",
"title": "ProductVariantsWriteRequest",
"description": "POST /api/v1/products/{id}/variants body. Up to 100 variants, cents-native. Each row is matched to an existing variant by external_id, then sku (any case), then the exact option_name + option_value pair (plus option2_name + option2_value when the variant has a second axis, e.g. Size x Colour), and updated IN PLACE; unmatched rows are inserted. Nothing is ever deleted. `mode` merge (default) leaves unlisted variants alone; replace deactivates them — except a variant an open order points at, which stays active and keeps its option / SKU / external id (reported in variant_sync.protected / identity_locked; its stock, price and image still update). `stock` is ABSOLUTE, never a delta. Rows may not repeat an external_id, a SKU (any case) or an option pair.",
"x-generated": "2026-10-30",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/xavio-in-openapi.json#/components/schemas/ProductVariantsWriteRequest",
"type": "object",
"properties": {
"variants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"external_id": {
"type": [
"string",
"null"
],
"minLength": 0,
"maxLength": 120
},
"sku": {
"type": [
"string",
"null"
],
"minLength": 0,
"maxLength": 60
},
"option_name": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"option_value": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"option2_name": {
"type": [
"string",
"null"
],
"minLength": 0,
"maxLength": 40
},
"option2_value": {
"type": [
"string",
"null"
],
"minLength": 0,
"maxLength": 60
},
"price_cents": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 1000000000
},
"compare_at_cents": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 1000000000
},
"stock": {
"type": "integer",
"minimum": 0,
"maximum": 1000000
},
"media_url": {
"type": [
"string",
"null"
],
"maxLength": 2048
},
"position": {
"type": "integer",
"minimum": -1000000,
"maximum": 1000000
},
"is_active": {
"type": "boolean"
},
"gtin": {
"type": [
"string",
"null"
],
"minLength": 0,
"maxLength": 40
},
"weight_grams": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 500000
},
"ship_length_mm": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 5000000
},
"ship_width_mm": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 5000000
},
"ship_height_mm": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 5000000
}
},
"required": [
"option_name",
"option_value"
]
}
},
"mode": {
"type": "string",
"enum": [
"merge",
"replace"
]
}
},
"required": [
"variants"
]
}
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.