POST /v1/items/{id}/variants

Scope

write_items

Request parameters

Name	In	Type	Required	Description
id	path	string	required	ID of the target resource.
Idempotency-Key	header	string	required	Idempotency key (required). A UUID v4 is recommended. Resending the same key replays the original result, and the response carries Idempotent-Replay: true. Sending a different body with the same key returns 422, so always retry with the identical request.
sku	body	string	required	SKU for this variant.
axis_values	body	array	required	Axis values for the variant being added. Give a value for every axis of the item, and no others.
price	body	object	optional	Price for this variant. null falls back to the item's price.
inventory	body	integer	optional	Initial stock only. After creation, update it through the stock endpoint with variant_id.
discount_rate	body	integer	optional	Discount rate for this variant, in percent.
status	body	enum(active	inactive)	optional

Response example

{
  "data": {
    "id": "string",
    "item_id": "string",
    "sku": "string",
    "name": "string",
    "price": {
      "amount": 0,
      "currency": "JPY"
    },
    "discount_rate": 0,
    "inventory": 0,
    "status": "active",
    "axis_values": [
      {
        "axis": "string",
        "value": "string"
      }
    ]
  }
}

Description

Add a variant. Only combinations of the item's existing variation axes are accepted. (write_items)

Error response example

{
  "error": {
    "code": "insufficient_scope",
    "message": "requires scope 'write_items'",
    "request_id": "req_01H..."
  }
}

Possible errors: 400 / 401 / 403 / 404 / 409 / 422 / 503