API Catalogue2026-11Aperçu

Variantes

Une option d’un produit, une taille, une couleur ou un modèle de téléphone, liée au SKU du vendeur que nous achetons et à la variante que vend votre boutique.

Une variante est ce que nomme une ligne de commande. Son niveau de stock indique combien vous pouvez en vendre.

Endpoints

GET/v1/products/{id}/variantsLister les variantes d’un produit
GET/v1/variants/{id}Récupérer une variante
PATCH/v1/variants/{id}Modifier une variante

L’objet Variant

idstring: Commence par var_.
skustring: Le SKU du vendeur, tel que nous l’avons lu. Ce que nous achetons.
label, options: Les valeurs d’option, en un libellé et par nom d’option.
costmoney: Ce que le vendeur facture pour une unité, en CN¥, selon la dernière lecture.
pricemoney: Votre prix de vente.
in_stockboolean: Si le vendeur peut le vendre, selon la dernière lecture.
unitsinteger: Combien nous en achetons pour chaque unité vendue : un lot de 3 dans votre boutique en achète 3.
weight_ginteger: Le poids emballé que vous avez indiqué pour une unité, utilisé pour estimer l’expédition.
external_variant_idstring|null: La variante de votre boutique. Une commande de celle-ci achète ce SKU ; une commande d’une variante non associée est refusée.

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

Lister les variantes d’un produit

GET/v1/products/{id}/variants

Chaque variante avec son coût, votre prix, son stock et son association.

Scopeproducts:read

Paramètres de chemin

idstringobligatoire: L’identifiant du produit.

Paramètres de requête

limit, cursor: Pagination

Erreurs

Statut	Type	Quand
404	not-found	Aucun produit de ce type sur ce compte.

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
}

Récupérer une variante

GET/v1/variants/{id}

Une variante.

Scopeproducts:read

Paramètres de chemin

idstringobligatoire: L’identifiant de la variante.

Erreurs

Statut	Type	Quand
404	not-found	Aucune variante de ce type sur ce compte.

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

Modifier une variante

PATCH/v1/variants/{id}

Fixez son prix, les unités achetées par vente, son poids, ou la variante de la boutique à laquelle il correspond. N’envoyez que ce qui change.

Scopeproducts:write

Paramètres de chemin

idstringobligatoire: L’identifiant de la variante.

Corps

pricemoney: Facultatif. Votre prix de vente.
unitsinteger: Facultatif. 1 à 50.
weight_ginteger: Facultatif. Poids emballé d’une unité, en grammes.
external_variant_idstring|null: Facultatif. Associez-la à une variante de votre boutique, ou null pour la dissocier.

Erreurs

Statut	Type	Quand
404	not-found	Aucune variante de ce type sur ce compte.
409	invalid-state	Cette variante de boutique correspond déjà à un autre 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"
}