Developers
Products

Set or adjust stock

POST
/products/{id}/variants/{variant_id}/stock

Sets a variant's stock to a quantity (set) or changes it by an amount (adjust, e.g. -3). Stock can't go below zero. Every change is recorded in the store's stock history.

Authorization

apiKey
headerAuthorizationBearer <token>

A store API key from Settings → Developers → API keys, sent as Authorization: Bearer zk_live_….

Path Parameters

id*string

The resource id

Formatuuid
variant_id*string

The variant id

Formatuuid

Header Parameters

Idempotency-Key?string

A unique value (e.g. a UUID) per change. Retrying with the same key returns the first result instead of applying the change twice. Kept for 24 hours.

Lengthlength <= 255

Request Body

application/json
  1. body
mode*string

set replaces the quantity; adjust adds to it

Value in"set""adjust"
quantity*integer

set: the new quantity (≥ 0). adjust: the change (≠ 0)

note?string
Lengthlength <= 200

Response Body

Success

application/json
  1. response
object*"product_variant"
Value in"product_variant"
id*string
product_id*string
title*string
sku*string
barcode*string
price*string

Full price, before the variant discount

discount_type*string
Value in"percentage""fixed"
discount_value*string

Decimal amount as a string, e.g. "149.00"

stock*integer

Units in stock; null when stock isn't tracked

low_stock_threshold*integer
option1*string
option2*string
option3*string
position*integer
image_url*string
created_at*string

ISO 8601 timestamp

updated_at*string

ISO 8601 timestamp

curl -X POST "https://example.com/products/497f6eca-6276-4993-bfeb-53cbbbba6f08/variants/497f6eca-6276-4993-bfeb-53cbbbba6f08/stock" \  -H "Content-Type: application/json" \  -d '{    "mode": "set",    "quantity": 0  }'
{  "object": "product_variant",  "id": "00000000-0000-4000-8000-0000000000b1",  "product_id": "00000000-0000-4000-8000-0000000000a1",  "title": "Medium / Black",  "sku": "TSHIRT-M-BLK",  "barcode": null,  "price": "120.00",  "discount_type": "percentage",  "discount_value": "10.00",  "stock": 42,  "low_stock_threshold": 5,  "option1": "Medium",  "option2": "Black",  "option3": null,  "position": 1,  "image_url": null,  "created_at": "2026-09-01T08:00:00.000Z",  "updated_at": "2026-10-01T09:30:00.000Z"}

Update a variant's price PATCH

Changes a variant's price and discount. Only the fields you send change. The discount must leave a price above zero. Returns the whole product.

List customers GET

Lists the store's customers, newest first, with contact details and marketing status. Filter by exact email or date.