Catalog API2026-11Preview
Variants
One option of a product, a size, a colour or a phone model, tied to the seller's SKU we buy and to the variant your store sells.
A variant is what an order line names. Its inventory level says how many you can sell.
The Variant object
idstring- Starts var_.
skustring- The seller's SKU, as we read it. What we buy.
label, options- The option values, as one label and by option name.
costmoney- What the seller charges for one, in CN¥, as last read.
pricemoney- Your selling price.
in_stockboolean- Whether the seller can sell it, as last read.
unitsinteger- How many we buy for each one you sell: a pack of 3 on your store buys 3.
weight_ginteger- The packed weight you gave for one, used to estimate shipping.
external_variant_idstring|null- Your store's variant. An order for it buys this SKU; an order for an unmapped variant is turned down.
{
"id": "var_41hz",
"product": "prd_8f2k",
"sku": "5187209554",
"label": "Black / M",
"options": { "Color": "Black", "Size": "M" },
"image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
"cost": { "amount": "38.00", "currency": "CNY" },
"price": { "amount": "49.99", "currency": "USD" },
"in_stock": true,
"units": 1,
"weight_g": 180,
"external_variant_id": "gid://shopify/ProductVariant/44100231",
"updated_at": "2026-11-04T09:20:03Z"
}List a product's variants
GET/v1/products/{id}/variants
Every variant with its cost, your price, stock and mapping.
Scopeproducts:read
Path parameters
idstringrequired- The product's id.
Query parameters
limit, cursor- Pagination
Errors
| Status | Type | When |
|---|---|---|
| 404 | not-found | No such product on this account. |
curl "https://www.ninjabuy.com/api/v1/products/prd_8f2k/variants" \
-H "Authorization: Bearer $NINJABUY_API_KEY" \
-H "NinjaBuy-Version: 2026-11"HTTP/2 200 OK
{
"data": [
{
"id": "var_41hz",
"product": "prd_8f2k",
"sku": "5187209554",
"label": "Black / M",
"options": { "Color": "Black", "Size": "M" },
"image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
"cost": { "amount": "38.00", "currency": "CNY" },
"price": { "amount": "49.99", "currency": "USD" },
"in_stock": true,
"units": 1,
"weight_g": 180,
"external_variant_id": "gid://shopify/ProductVariant/44100231",
"updated_at": "2026-11-04T09:20:03Z"
},
{
"id": "var_41j0",
"product": "prd_8f2k",
"sku": "5187209555",
"label": "Black / L",
"options": { "Color": "Black", "Size": "M" },
"image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
"cost": { "amount": "38.00", "currency": "CNY" },
"price": { "amount": "49.99", "currency": "USD" },
"in_stock": false,
"units": 1,
"weight_g": 180,
"external_variant_id": null,
"updated_at": "2026-11-04T09:20:03Z"
}
],
"has_more": false,
"cursor": null
}Retrieve a variant
GET/v1/variants/{id}
One variant.
Scopeproducts:read
Path parameters
idstringrequired- The variant's id.
Errors
| Status | Type | When |
|---|---|---|
| 404 | not-found | No such variant on this account. |
curl "https://www.ninjabuy.com/api/v1/variants/var_41hz" \
-H "Authorization: Bearer $NINJABUY_API_KEY" \
-H "NinjaBuy-Version: 2026-11"HTTP/2 200 OK
{
"id": "var_41hz",
"product": "prd_8f2k",
"sku": "5187209554",
"label": "Black / M",
"options": { "Color": "Black", "Size": "M" },
"image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
"cost": { "amount": "38.00", "currency": "CNY" },
"price": { "amount": "49.99", "currency": "USD" },
"in_stock": true,
"units": 1,
"weight_g": 180,
"external_variant_id": "gid://shopify/ProductVariant/44100231",
"updated_at": "2026-11-04T09:20:03Z"
}Update a variant
PATCH/v1/variants/{id}
Set its price, the units bought per sale, its weight, or the store variant it answers for. Send only what changes.
Scopeproducts:write
Path parameters
idstringrequired- The variant's id.
Body
pricemoney- Optional. Your selling price.
unitsinteger- Optional. 1 to 50.
weight_ginteger- Optional. Packed weight of one, in grams.
external_variant_idstring|null- Optional. Map it to a variant in your store, or null to unmap it.
Errors
| Status | Type | When |
|---|---|---|
| 404 | not-found | No such variant on this account. |
| 409 | invalid-state | That store variant already answers for another SKU. |
curl -X PATCH "https://www.ninjabuy.com/api/v1/variants/var_41hz" \
-H "Authorization: Bearer $NINJABUY_API_KEY" \
-H "NinjaBuy-Version: 2026-11" \
-H "Content-Type: application/json" \
-d '{
"units": 2,
"price": { "amount": "89.99", "currency": "USD" }
}'HTTP/2 200 OK
{
"id": "var_41hz",
"product": "prd_8f2k",
"sku": "5187209554",
"label": "Black / M",
"options": { "Color": "Black", "Size": "M" },
"image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
"cost": { "amount": "38.00", "currency": "CNY" },
"price": { "amount": "89.99", "currency": "USD" },
"in_stock": true,
"units": 2,
"weight_g": 180,
"external_variant_id": "gid://shopify/ProductVariant/44100231",
"updated_at": "2026-11-04T09:20:03Z"
}