{
  "$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"
  ]
}