API Catalogue2026-11Aperçu

Produits

Une annonce enregistrée depuis un import, avec votre titre, vos prix et les boutiques où elle est vendue.

C’est dans Shopify que les produits sont envoyés. Les commandes des marketplaces où vend votre boutique Shopify nous parviennent aussi via Shopify : Connecter une boutique.
Une boutique WooCommerce ou Wix garde ses propres produits et envoie ses commandes avec Créer une commande.

Endpoints

GET/v1/productsLister les produits
GET/v1/products/{id}Récupérer un produit
PATCH/v1/products/{id}Modifier un produit
POST/v1/products/{id}/pushPush to Shopify
DELETE/v1/products/{id}Supprimer un produit

L’objet Product

idstring: Commence par prd_.
titlestring: Votre titre. Celui du vendeur reste sur l’import.
statusstring: active, ou en pause (par vous, ou par une règle de synchronisation quand un coût a trop augmenté ou que le vendeur est en rupture).
sourceobject: Marketplace, lien de l’annonce et vendeur en Chine.
options[]array: Noms des options, trois au maximum, tels que votre boutique les affiche.
price_range, cost_rangeobject: Vos prix et ceux du vendeur, pour chaque variante.
channels[]array: Où il est publié : la boutique, son propre identifiant de produit, et son statut là-bas.
syncobject: La règle de synchronisation qu’il suit et la date de notre dernière lecture de l’annonce.
importstring: L’import d’où il a été enregistré.

product

{
  "id": "prd_8f2k",
  "title": "Heavyweight Washed Hoodie",
  "status": "active",
  "source": {
    "marketplace": "weidian",
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "seller": "Ruoyi Studio"
  },
  "options": ["Color", "Size"],
  "variants_count": 6,
  "price_range": {
    "min": { "amount": "49.99", "currency": "USD" },
    "max": { "amount": "54.99", "currency": "USD" }
  },
  "cost_range": {
    "min": { "amount": "38.00", "currency": "CNY" },
    "max": { "amount": "42.00", "currency": "CNY" }
  },
  "channels": [
    {
      "channel": "shopify",
      "shop": "acme-goods.myshopify.com",
      "external_id": "gid://shopify/Product/8812042",
      "status": "draft",
      "pushed_at": "2026-11-04T09:20:03Z"
    }
  ],
  "sync": {
    "rule": "rule_default",
    "last_checked_at": "2026-11-04T09:12:40Z"
  },
  "import": "imp_2c9d",
  "created_at": "2026-11-04T09:20:01Z",
  "updated_at": "2026-11-04T09:20:03Z"
}

Lister les produits

GET/v1/products

Vos produits, les plus récents d’abord.

Scopeproducts:read

Paramètres de requête

statusstring: Facultatif. active ou paused.
channelstring: Facultatif. shopify, pour ceux qui y sont publiés.
changed_sincestring: Facultatif. Une date : seulement les produits dont le coût ou le stock a changé depuis.
limit, cursor: Pagination

curl "https://www.ninjabuy.com/api/v1/products?status=active&limit=2" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "prd_8f2k",
      "title": "Heavyweight Washed Hoodie",
      "status": "active",
      "variants_count": 6
    },
    {
      "id": "prd_1x0a",
      "title": "Canvas Tote",
      "status": "active",
      "variants_count": 3
    }
  ],
  "has_more": true,
  "cursor": "c_1x0a"
}

Récupérer un produit

GET/v1/products/{id}

Un produit avec sa source, ses canaux et son état de synchronisation. Ses variantes ont leur propre route.

Scopeproducts:read

Paramètres de chemin

idstringobligatoire: L’identifiant du produit.

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" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "id": "prd_8f2k",
  "title": "Heavyweight Washed Hoodie",
  "status": "active",
  "source": {
    "marketplace": "weidian",
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "seller": "Ruoyi Studio"
  },
  "options": ["Color", "Size"],
  "variants_count": 6,
  "price_range": {
    "min": { "amount": "49.99", "currency": "USD" },
    "max": { "amount": "54.99", "currency": "USD" }
  },
  "cost_range": {
    "min": { "amount": "38.00", "currency": "CNY" },
    "max": { "amount": "42.00", "currency": "CNY" }
  },
  "channels": [
    {
      "channel": "shopify",
      "shop": "acme-goods.myshopify.com",
      "external_id": "gid://shopify/Product/8812042",
      "status": "draft",
      "pushed_at": "2026-11-04T09:20:03Z"
    }
  ],
  "sync": {
    "rule": "rule_default",
    "last_checked_at": "2026-11-04T09:12:40Z"
  },
  "import": "imp_2c9d",
  "created_at": "2026-11-04T09:20:01Z",
  "updated_at": "2026-11-04T09:20:03Z"
}

Modifiez le titre ou la description, ou mettez en pause et reprenez. N’envoyez que ce qui change. Les prix sont par variante (Variants) ; un produit envoyé reporte le changement dans votre boutique au prochain envoi.

Scopeproducts:write

Paramètres de chemin

idstringobligatoire: L’identifiant du produit.

Corps

titlestring: Facultatif.
descriptionstring: Facultatif. Le HTML affiché par votre boutique.
statusstring: Facultatif. active ou paused. paused met le stock à 0 sur vos canaux.
sync_rulestring: Facultatif. Un identifiant de règle de synchronisation ; la règle par défaut si null.

Erreurs

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

curl -X PATCH "https://www.ninjabuy.com/api/v1/products/prd_8f2k" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

Response 200

HTTP/2 200 OK

{
  "id": "prd_8f2k",
  "title": "Heavyweight Washed Hoodie",
  "status": "paused",
  "source": {
    "marketplace": "weidian",
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "seller": "Ruoyi Studio"
  },
  "options": ["Color", "Size"],
  "variants_count": 6,
  "price_range": {
    "min": { "amount": "49.99", "currency": "USD" },
    "max": { "amount": "54.99", "currency": "USD" }
  },
  "cost_range": {
    "min": { "amount": "38.00", "currency": "CNY" },
    "max": { "amount": "42.00", "currency": "CNY" }
  },
  "channels": [
    {
      "channel": "shopify",
      "shop": "acme-goods.myshopify.com",
      "external_id": "gid://shopify/Product/8812042",
      "status": "draft",
      "pushed_at": "2026-11-04T09:20:03Z"
    }
  ],
  "sync": {
    "rule": "rule_default",
    "last_checked_at": "2026-11-04T09:12:40Z"
  },
  "import": "imp_2c9d",
  "created_at": "2026-11-04T09:20:01Z",
  "updated_at": "2026-11-04T09:20:03Z"
}

Push to Shopify

POST/v1/products/{id}/push

Publie le produit dans votre boutique Shopify liée : un produit Shopify, une variante par SKU conservé, ses photos, chaque variante stockée à l’emplacement Fulfilled by NinjaBuy, pour que ses commandes nous parviennent.

Le premier envoi le crée en brouillon : le titre et les photos viennent d’une marketplace chinoise, lisez-les donc avant vos acheteurs, puis publiez dans Shopify.
Renvoyer met à jour le même produit Shopify : les prix et le stock sont redéfinis, les variantes écartées sont supprimées. Le statut, le titre, la description et les photos restent tels que vous les avez laissés dans Shopify, sauf si vous en envoyez de nouveaux.
Le stock est celui du vendeur, plafonné à 100 : nous achetons à la demande, c’est donc le nombre de commandes que Shopify accepte avant d’afficher épuisé.
Votre boutique doit vendre en US$, puisque les prix y sont exprimés. Les variantes épuisées sont ignorées et nommées dans skipped[].

Scopeproducts:write

Paramètres de chemin

idstringobligatoire: L’identifiant du produit.

Corps

shopstring: Quelle boutique liée, par exemple acme-goods.myshopify.com. Requis seulement si vous en avez lié plusieurs.
title, descriptionstring: Facultatif. Envoyés à Shopify seulement si vous les envoyez.

Erreurs

Statut	Type	Quand
409	no-linked-store	Aucune boutique Shopify n’est liée à ce compte, ou plusieurs le sont et `shop` manque.
409	store-not-ready	L’accès de la boutique a expiré, ou notre emplacement n’est pas encore configuré : ouvrez une fois l’app NinjaBuy dans Shopify.
422	store-currency	La boutique ne vend pas en US$.
422	too-many-options	L’annonce a plus de trois options ; Shopify en prend trois.
422	unprocessable	Toutes les variantes sont épuisées, ou Shopify a refusé un champ ; detail transmet son message.

curl -X POST "https://www.ninjabuy.com/api/v1/products/prd_8f2k/push" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "shop": "acme-goods.myshopify.com" }'

Response 200

HTTP/2 200 OK

{
  "channel": "shopify",
  "shop": "acme-goods.myshopify.com",
  "external_id": "gid://shopify/Product/8812042",
  "status": "draft",
  "created": true,
  "variants": 5,
  "skipped": [{ "sku": "5187209555", "reason": "sold_out" }],
  "admin_url": "https://admin.shopify.com/store/acme-goods/products/8812042"
}

Supprimer un produit

DELETE/v1/products/{id}

Arrête sa synchronisation et met son stock à 0 sur vos canaux ; le produit Shopify reste, à vous de l’archiver. Les commandes déjà passées partent quand même.

Scopeproducts:write

Paramètres de chemin

idstringobligatoire: L’identifiant du produit.

Erreurs

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

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

Response 200

HTTP/2 200 OK

{ "id": "prd_8f2k", "deleted": true }

L’objet Product

Lister les produits

Paramètres de requête

Récupérer un produit

Paramètres de chemin

Erreurs

Modifier un produit

Paramètres de chemin

Corps

Erreurs

Push to Shopify

Paramètres de chemin

Corps

Erreurs

Supprimer un produit

Paramètres de chemin

Erreurs