Create a variant

POST

api

admin

products

{product_id}

variants

Spree Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

const variant = await client.products.variants.create('prod_86Rf07xd4z', {
  sku: 'TSHIRT-L-NAVY',
  options: [
    { name: 'size', value: 'Large' },
    { name: 'color', value: 'navy' },
  ],
  prices: [
    { currency: 'USD', amount: '29.99', compare_at_amount: '34.99' },
    { currency: 'EUR', amount: '27.99' },
  ],
  stock_items: [{ stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 25 }],
})

spree api post /products/{product_id}/variants -d '{"sku":"TSHIRT-L-NAVY","options":[{"name":"size","value":"Large"},{"name":"color","value":"navy"}],"prices":[{"currency":"USD","amount":"29.99","compare_at_amount":"34.99"},{"currency":"EUR","amount":"27.99"}],"stock_items":[{"stock_location_id":"sloc_UkLWZg9DAJ","count_on_hand":25}]}'

{
  "id": "variant_EfhxLZ9ck8",
  "product_id": "prod_UkLWZg9DAJ",
  "sku": "NEW-SKU-001",
  "options_text": "Size: XL",
  "track_inventory": true,
  "media_count": 0,
  "preorder_ships_at": null,
  "thumbnail_url": null,
  "purchasable": false,
  "in_stock": false,
  "backorderable": false,
  "preorder": false,
  "weight": 0,
  "height": null,
  "width": null,
  "depth": null,
  "price": {
    "id": "price_EfhxLZ9ck8",
    "amount": "24.99",
    "amount_in_cents": 2499,
    "compare_at_amount": null,
    "compare_at_amount_in_cents": null,
    "currency": "USD",
    "display_amount": "$24.99",
    "display_compare_at_amount": null,
    "price_list_id": null
  },
  "original_price": null,
  "option_values": [
    {
      "id": "optval_gbHJdmfrXB",
      "option_type_id": "opt_gbHJdmfrXB",
      "name": "xl",
      "label": "XL",
      "position": 1,
      "color_code": null,
      "option_type_name": "size",
      "option_type_label": "Size",
      "image_url": null,
      "metadata": {},
      "created_at": "2026-07-27T20:01:45.783Z",
      "updated_at": "2026-07-27T20:01:45.783Z"
    }
  ],
  "metadata": {},
  "position": 3,
  "cost_price": null,
  "cost_currency": "USD",
  "barcode": null,
  "weight_unit": "lb",
  "dimensions_unit": null,
  "backorder_limit": null,
  "deleted_at": null,
  "created_at": "2026-07-27T20:01:45.786Z",
  "updated_at": "2026-07-27T20:01:45.788Z",
  "preorderable": false,
  "tax_category_id": "taxcat_UkLWZg9DAJ",
  "available_stock": 0,
  "reserved_quantity": 0,
  "total_on_hand": 0,
  "product_name": "Product 852654"
}

{
  "error": {
    "code": "validation_error",
    "message": "Option value variants can't be blank",
    "details": {
      "option_value_variants": [
        "can't be blank"
      ]
    }
  }
}

Authorizations

x-spree-api-key

string

header

required

Secret API key for admin access

Authorization

string

header

required

JWT token for admin user authentication

Headers

x-spree-api-key

string

required

Authorization

string

required

Bearer token for admin authentication

Path Parameters

product_id

string

required

Product ID

Body

application/json

options

object[]

required

Required. A variant created here is always non-master, so it must declare at least one option pair (e.g. size + color) or creation fails with 422. One pair per option type the variant participates in. Option types and values are auto-created if missing.

Show child attributes

sku

string

Example:

"SKU-001"

cost_price

string

Example:

"10.00"

cost_currency

string

Example:

"USD"

weight

number

height

number

width

number

depth

number

weight_unit

string

dimensions_unit

string

track_inventory

boolean

tax_category_id

string

position

integer

barcode

string

prices

object[]

Per-currency prices. Upserted by currency.

Show child attributes

stock_items

object[]

Per-stock-location inventory. Upserted by stock_location_id.

Show child attributes

Response

variant created

List product variants

Get a variant

⌘I

Spree Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

const variant = await client.products.variants.create('prod_86Rf07xd4z', {
  sku: 'TSHIRT-L-NAVY',
  options: [
    { name: 'size', value: 'Large' },
    { name: 'color', value: 'navy' },
  ],
  prices: [
    { currency: 'USD', amount: '29.99', compare_at_amount: '34.99' },
    { currency: 'EUR', amount: '27.99' },
  ],
  stock_items: [{ stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 25 }],
})

spree api post /products/{product_id}/variants -d '{"sku":"TSHIRT-L-NAVY","options":[{"name":"size","value":"Large"},{"name":"color","value":"navy"}],"prices":[{"currency":"USD","amount":"29.99","compare_at_amount":"34.99"},{"currency":"EUR","amount":"27.99"}],"stock_items":[{"stock_location_id":"sloc_UkLWZg9DAJ","count_on_hand":25}]}'

{
  "id": "variant_EfhxLZ9ck8",
  "product_id": "prod_UkLWZg9DAJ",
  "sku": "NEW-SKU-001",
  "options_text": "Size: XL",
  "track_inventory": true,
  "media_count": 0,
  "preorder_ships_at": null,
  "thumbnail_url": null,
  "purchasable": false,
  "in_stock": false,
  "backorderable": false,
  "preorder": false,
  "weight": 0,
  "height": null,
  "width": null,
  "depth": null,
  "price": {
    "id": "price_EfhxLZ9ck8",
    "amount": "24.99",
    "amount_in_cents": 2499,
    "compare_at_amount": null,
    "compare_at_amount_in_cents": null,
    "currency": "USD",
    "display_amount": "$24.99",
    "display_compare_at_amount": null,
    "price_list_id": null
  },
  "original_price": null,
  "option_values": [
    {
      "id": "optval_gbHJdmfrXB",
      "option_type_id": "opt_gbHJdmfrXB",
      "name": "xl",
      "label": "XL",
      "position": 1,
      "color_code": null,
      "option_type_name": "size",
      "option_type_label": "Size",
      "image_url": null,
      "metadata": {},
      "created_at": "2026-07-27T20:01:45.783Z",
      "updated_at": "2026-07-27T20:01:45.783Z"
    }
  ],
  "metadata": {},
  "position": 3,
  "cost_price": null,
  "cost_currency": "USD",
  "barcode": null,
  "weight_unit": "lb",
  "dimensions_unit": null,
  "backorder_limit": null,
  "deleted_at": null,
  "created_at": "2026-07-27T20:01:45.786Z",
  "updated_at": "2026-07-27T20:01:45.788Z",
  "preorderable": false,
  "tax_category_id": "taxcat_UkLWZg9DAJ",
  "available_stock": 0,
  "reserved_quantity": 0,
  "total_on_hand": 0,
  "product_name": "Product 852654"
}

{
  "error": {
    "code": "validation_error",
    "message": "Option value variants can't be blank",
    "details": {
      "option_value_variants": [
        "can't be blank"
      ]
    }
  }
}

API basics

Endpoints

Authorizations

Headers

Path Parameters

Body

Response