API Catalogo2026-11Anteprima

Varianti

Un’opzione di un prodotto, una taglia, un colore o un modello di telefono, legata allo SKU del venditore che acquistiamo e alla variante che vende il tuo negozio.

Una variante è ciò che indica una riga d’ordine. Il suo livello di stock dice quanti pezzi puoi vendere.

Endpoint

GET/v1/products/{id}/variantsElenca le varianti di un prodotto
GET/v1/variants/{id}Recupera una variante
PATCH/v1/variants/{id}Aggiorna una variante

L’oggetto Variant

idstring: Inizia con var_.
skustring: Lo SKU del venditore, come lo leggiamo. Ciò che acquistiamo.
label, options: I valori delle opzioni, come un’etichetta unica e per nome di opzione.
costmoney: Quanto chiede il venditore per un’unità, in CN¥, all’ultima lettura.
pricemoney: Il tuo prezzo di vendita.
in_stockboolean: Se il venditore può venderlo, all’ultima lettura.
unitsinteger: Quanti ne acquistiamo per ognuno che vendi: una confezione da 3 nel tuo negozio ne acquista 3.
weight_ginteger: Il peso imballato che hai indicato per un’unità, usato per stimare la spedizione.
external_variant_idstring|null: La variante del tuo negozio. Un suo ordine acquista questo SKU; un ordine per una variante non associata viene rifiutato.

variant

{
  "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"
}

Elenca le varianti di un prodotto

GET/v1/products/{id}/variants

Ogni variante con costo, tuo prezzo, stock e associazione.

Scopeproducts:read

Parametri di percorso

idstringobbligatorio: L’ID del prodotto.

Parametri di query

limit, cursor: Pagination

Errori

Stato	Tipo	Quando
404	not-found	Nessun prodotto simile su questo account.

curl "https://www.ninjabuy.com/api/v1/products/prd_8f2k/variants" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

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
}

Recupera una variante

GET/v1/variants/{id}

Una variante.

Scopeproducts:read

Parametri di percorso

idstringobbligatorio: L’ID della variante.

Errori

Stato	Tipo	Quando
404	not-found	Nessuna variante simile su questo account.

curl "https://www.ninjabuy.com/api/v1/variants/var_41hz" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

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"
}

Aggiorna una variante

PATCH/v1/variants/{id}

Imposta il suo prezzo, le unità acquistate per vendita, il peso o la variante del negozio a cui corrisponde. Invia solo ciò che cambia.

Scopeproducts:write

Parametri di percorso

idstringobbligatorio: L’ID della variante.

Corpo

pricemoney: Facoltativo. Il tuo prezzo di vendita.
unitsinteger: Facoltativo. Da 1 a 50.
weight_ginteger: Facoltativo. Peso imballato di un’unità, in grammi.
external_variant_idstring|null: Facoltativo. Associala a una variante del tuo negozio, o null per rimuovere l’associazione.

Errori

Stato	Tipo	Quando
404	not-found	Nessuna variante simile su questo account.
409	invalid-state	Quella variante del negozio corrisponde già a un altro 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" }
  }'

Response 200

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"
}