Update a variant

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.update('prod_86Rf07xd4z', 'variant_k5nR8xLq', {
  sku: 'UPDATED-SKU',
  stock_levels: [{ stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 75 }],
})

{
  "id": "variant_gbHJdmfrXB",
  "product_id": "prod_UkLWZg9DAJ",
  "sku": "UPDATED-SKU",
  "options_text": "Size: S",
  "track_inventory": true,
  "media_count": 0,
  "preorder_ships_at": null,
  "thumbnail_url": null,
  "purchasable": true,
  "in_stock": false,
  "backorderable": true,
  "preorder": false,
  "weight": 85.5,
  "height": 120.69,
  "width": 57.61,
  "depth": 3.72,
  "weight_unit": "lb",
  "dimensions_unit": "in",
  "minimum_order_quantity": null,
  "order_multiple": null,
  "purchase_unit": null,
  "units_per_carton": null,
  "price": {
    "id": "price_gbHJdmfrXB",
    "currency": "USD",
    "amount": "19.99",
    "compare_at_amount": null,
    "price_list_id": null,
    "min_quantity": 1,
    "variant_id": "variant_gbHJdmfrXB",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  },
  "original_price": null,
  "seller_id": null,
  "option_values": [
    {
      "id": "optval_UkLWZg9DAJ",
      "option_type_id": "opt_UkLWZg9DAJ",
      "name": "size-75",
      "label": "S",
      "position": 1,
      "color_code": null,
      "option_type_name": "foo-size-85",
      "option_type_label": "Size",
      "image_url": null,
      "metadata": {},
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "external_references": {},
  "metadata": {},
  "position": 2,
  "cost_currency": "USD",
  "barcode": null,
  "backorder_limit": null,
  "hs_code": null,
  "country_of_origin": null,
  "customs_description": null,
  "carton_weight": null,
  "cartons_per_pallet": null,
  "deleted_at": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "cost_price": "17.00",
  "preorderable": false,
  "tax_category_id": null,
  "carton_package_type_id": null,
  "units_per_pallet": null,
  "available_stock": 0,
  "reserved_quantity": 0,
  "total_on_hand": 0,
  "product_name": "Product 2195672",
  "delivery_profile_id": "fp_UkLWZg9DAJ"
}

PATCH

api

admin

products

{product_id}

variants

{id}

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.update('prod_86Rf07xd4z', 'variant_k5nR8xLq', {
  sku: 'UPDATED-SKU',
  stock_levels: [{ stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 75 }],
})

{
  "id": "variant_gbHJdmfrXB",
  "product_id": "prod_UkLWZg9DAJ",
  "sku": "UPDATED-SKU",
  "options_text": "Size: S",
  "track_inventory": true,
  "media_count": 0,
  "preorder_ships_at": null,
  "thumbnail_url": null,
  "purchasable": true,
  "in_stock": false,
  "backorderable": true,
  "preorder": false,
  "weight": 85.5,
  "height": 120.69,
  "width": 57.61,
  "depth": 3.72,
  "weight_unit": "lb",
  "dimensions_unit": "in",
  "minimum_order_quantity": null,
  "order_multiple": null,
  "purchase_unit": null,
  "units_per_carton": null,
  "price": {
    "id": "price_gbHJdmfrXB",
    "currency": "USD",
    "amount": "19.99",
    "compare_at_amount": null,
    "price_list_id": null,
    "min_quantity": 1,
    "variant_id": "variant_gbHJdmfrXB",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  },
  "original_price": null,
  "seller_id": null,
  "option_values": [
    {
      "id": "optval_UkLWZg9DAJ",
      "option_type_id": "opt_UkLWZg9DAJ",
      "name": "size-75",
      "label": "S",
      "position": 1,
      "color_code": null,
      "option_type_name": "foo-size-85",
      "option_type_label": "Size",
      "image_url": null,
      "metadata": {},
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "external_references": {},
  "metadata": {},
  "position": 2,
  "cost_currency": "USD",
  "barcode": null,
  "backorder_limit": null,
  "hs_code": null,
  "country_of_origin": null,
  "customs_description": null,
  "carton_weight": null,
  "cartons_per_pallet": null,
  "deleted_at": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "cost_price": "17.00",
  "preorderable": false,
  "tax_category_id": null,
  "carton_package_type_id": null,
  "units_per_pallet": null,
  "available_stock": 0,
  "reserved_quantity": 0,
  "total_on_hand": 0,
  "product_name": "Product 2195672",
  "delivery_profile_id": "fp_UkLWZg9DAJ"
}

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

string

required

Variant ID

Body

application/json

sku

string

barcode

string

cost_price

string<decimal> | null

Pattern: ^-?\d+(\.\d+)?$

cost_currency

enum<string>

Available options:

AED,

AFN,

ALL,

AMD,

ANG,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BTN,

BWP,

BYN,

BYR,

BZD,

CAD,

CDF,

CHF,

CLF,

CLP,

CNY,

COP,

CRC,

CUC,

CUP,

CVE,

CZK,

DJF,

DKK,

DOP,

DZD,

EEK,

EGP,

ERN,

ETB,

EUR,

FJD,

FKP,

GBP,

GEL,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

INR,

IQD,

IRR,

ISK,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KPW,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LTL,

LVL,

LYD,

MAD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRO,

MRU,

MTL,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

NGN,

NIO,

NOK,

NPR,

NZD,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SDG,

SEK,

SGD,

SHP,

SKK,

SLE,

SLL,

SOS,

SRD,

SSP,

STD,

STN,

SVC,

SYP,

SZL,

THB,

TJS,

TMM,

TMT,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYI,

UYU,

UYW,

UZS,

VED,

VEF,

VES,

VND,

VUV,

WST,

XAF,

XCD,

XCG,

XOF,

XPF,

YER,

ZAR,

ZMK,

ZMW,

ZWD,

ZWG,

ZWL,

ZWN,

ZWR

weight

number | null

height

number | null

width

number | null

depth

number | null

weight_unit

enum<string> | null

Null falls back to the store's weight unit.

Available options:

g,

kg,

lb,

oz

dimensions_unit

enum<string> | null

Null falls back to the store's unit system.

Available options:

mm,

cm,

in,

ft

hs_code

string

customs_description

string

country_of_origin

enum<string>

Available options:

AD,

AE,

AF,

AG,

AI,

AL,

AM,

AO,

AR,

AS,

AT,

AU,

AW,

AZ,

BA,

BB,

BD,

BE,

BF,

BG,

BH,

BI,

BJ,

BL,

BM,

BN,

BO,

BQ,

BR,

BS,

BT,

BW,

BY,

BZ,

CA,

CC,

CD,

CF,

CG,

CH,

CI,

CK,

CL,

CM,

CN,

CO,

CR,

CU,

CV,

CW,

CX,

CY,

CZ,

DE,

DJ,

DK,

DM,

DO,

DZ,

EC,

EE,

EG,

ER,

ES,

ET,

FI,

FJ,

FK,

FM,

FO,

FR,

GA,

GB,

GD,

GE,

GF,

GG,

GH,

GI,

GL,

GM,

GN,

GP,

GQ,

GR,

GT,

GU,

GW,

GY,

HK,

HN,

HR,

HT,

HU,

ID,

IE,

IL,

IM,

IN,

IQ,

IR,

IS,

IT,

JE,

JM,

JO,

JP,

KE,

KG,

KH,

KI,

KM,

KN,

KP,

KR,

KW,

KY,

KZ,

LA,

LB,

LC,

LI,

LK,

LR,

LS,

LT,

LU,

LV,

LY,

MA,

MC,

MD,

ME,

MF,

MG,

MH,

MK,

ML,

MM,

MN,

MO,

MP,

MQ,

MR,

MS,

MT,

MU,

MV,

MW,

MX,

MY,

MZ,

NA,

NC,

NE,

NF,

NG,

NI,

NL,

NO,

NP,

NR,

NU,

NZ,

OM,

PA,

PE,

PF,

PG,

PH,

PK,

PL,

PM,

PN,

PR,

PS,

PT,

PW,

PY,

QA,

RE,

RO,

RS,

RU,

RW,

SA,

SB,

SC,

SD,

SE,

SG,

SH,

SI,

SJ,

SK,

SL,

SM,

SN,

SO,

SR,

SS,

ST,

SV,

SX,

SY,

SZ,

TC,

TD,

TG,

TH,

TJ,

TK,

TL,

TM,

TN,

TO,

TR,

TT,

TV,

TW,

TZ,

UA,

UG,

US,

UY,

UZ,

VA,

VC,

VE,

VG,

VI,

VN,

VU,

WF,

WS,

YE,

YT,

ZA,

ZM,

ZW

minimum_order_quantity

integer | null

order_multiple

integer | null

purchase_unit

enum<string> | null

Available options:

unit,

carton

units_per_carton

integer | null

How many units fill one carton.

carton_package_type_id

string | null

The carton this variant is packed into: a package type of kind carton. Its dimensions are shared by every product packed the same way, so a corrected carton size fixes all of them at once.

carton_weight

number | null

What one packed carton weighs, in the variant's weight unit.

cartons_per_pallet

integer | null

How many cartons stack on one pallet.

track_inventory

boolean

preorderable

boolean

Sell this variant before it's in stock. Adds the pre-order label and ships-by promise; the cap comes from backorder_limit, an incoming stock count, or backorder.

preorder_ships_at

string<date-time> | null

The "ships by" date shown to customers while the variant is a pre-order. Once it passes, the variant is no longer a pre-order. Null clears it.

backorder_limit

integer | null

Maximum units sellable beyond available stock, capping backorders and pre-orders. Null is unlimited.

position

integer

options

object[]

One pair per option type the variant takes part in (size, color). Option types and values are created when missing. On update, omit to leave the option values untouched.

Show child attributes

seller_id

string

delivery_profile_id

string | null

tax_category_id

string

prices

object[]

Per-currency prices. Upserted by currency.

Show child attributes

stock_levels

object[]

Stock per location. Upserted by location; omitted locations are removed.

Show child attributes

external_references

object

Identities the record has in external systems, keyed by system: the same { system: external_id } map the Admin API renders, so what you read can be sent straight back. Systems you do not name keep the reference they have. A list of { system, external_id } entries is accepted too.

Response

200 - application/json

variant updated

⌘I

API basics

Endpoints

Authorizations

Headers

Path Parameters

Body

Response