API de catálogo2026-11Prévia
Variantes
Uma opção de um produto, um tamanho, uma cor ou um modelo de celular, ligada ao SKU do vendedor que compramos e à variante que a sua loja vende.
Uma variante é o que uma linha de pedido cita. O nível de estoque dela diz quantas você pode vender.
O objeto Variant
idstring- Começa com var_.
skustring- O SKU do vendedor, como o lemos. O que compramos.
label, options- Os valores das opções, como um rótulo e por nome de opção.
costmoney- Quanto o vendedor cobra por uma unidade, em CN¥, conforme a última leitura.
pricemoney- O seu preço de venda.
in_stockboolean- Se o vendedor pode vender, conforme a última leitura.
unitsinteger- Quantas compramos para cada uma que você vende: um kit de 3 na sua loja compra 3.
weight_ginteger- O peso embalado que você informou para uma unidade, usado para estimar o frete.
external_variant_idstring|null- A variante da sua loja. Um pedido dela compra este SKU; um pedido de uma variante não vinculada é recusado.
{
"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"
}Listar as variantes de um produto
GET/v1/products/{id}/variants
Cada variante com o custo, o seu preço, o estoque e o vínculo.
Escopoproducts:read
Parâmetros de caminho
idstringobrigatório- O id do produto.
Parâmetros de consulta
limit, cursor- Pagination
Erros
| Status | Tipo | Quando |
|---|---|---|
| 404 | not-found | Esse produto não existe nesta conta. |
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
}Obter uma variante
GET/v1/variants/{id}
Uma variante.
Escopoproducts:read
Parâmetros de caminho
idstringobrigatório- O id da variante.
Erros
| Status | Tipo | Quando |
|---|---|---|
| 404 | not-found | Essa variante não existe nesta conta. |
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"
}Atualizar uma variante
PATCH/v1/variants/{id}
Defina o preço, as unidades compradas por venda, o peso ou a variante da loja a que ela corresponde. Envie só o que muda.
Escopoproducts:write
Parâmetros de caminho
idstringobrigatório- O id da variante.
Corpo
pricemoney- Opcional. O seu preço de venda.
unitsinteger- Opcional. De 1 a 50.
weight_ginteger- Opcional. Peso embalado de uma unidade, em gramas.
external_variant_idstring|null- Opcional. Vincule a uma variante da sua loja, ou null para desvincular.
Erros
| Status | Tipo | Quando |
|---|---|---|
| 404 | not-found | Essa variante não existe nesta conta. |
| 409 | invalid-state | Essa variante da loja já corresponde a outro 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"
}