API de catálogo2026-11Vista previa

Variantes

Una opción de un producto, una talla, un color o un modelo de celular, ligada al SKU del vendedor que compramos y a la variante que vende tu tienda.

Una variante es lo que nombra una línea de pedido. Su nivel de inventario dice cuántas puedes vender.

Endpoints

GET/v1/products/{id}/variantsListar las variantes de un producto
GET/v1/variants/{id}Obtener una variante
PATCH/v1/variants/{id}Actualizar una variante

El objeto Variant

idstring: Empieza por var_.
skustring: El SKU del vendedor, tal como lo leímos. Lo que compramos.
label, options: Los valores de las opciones, como una etiqueta y por nombre de opción.
costmoney: Lo que cobra el vendedor por una unidad, en CN¥, según la última lectura.
pricemoney: Tu precio de venta.
in_stockboolean: Si el vendedor puede venderlo, según la última lectura.
unitsinteger: Cuántas compramos por cada una que vendes: un paquete de 3 en tu tienda compra 3.
weight_ginteger: El peso empacado que indicaste para una unidad, usado para estimar el envío.
external_variant_idstring|null: La variante de tu tienda. Un pedido de ella compra este SKU; un pedido de una variante sin vincular se rechaza.

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

Listar las variantes de un producto

GET/v1/products/{id}/variants

Cada variante con su costo, tu precio, el stock y la vinculación.

Alcanceproducts:read

Parámetros de ruta

idstringobligatorio: El id del producto.

Parámetros de consulta

limit, cursor: Pagination

Errores

Estado	Tipo	Cuándo
404	not-found	No existe ese producto en esta cuenta.

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
}

Obtener una variante

GET/v1/variants/{id}

Una variante.

Alcanceproducts:read

Parámetros de ruta

idstringobligatorio: El id de la variante.

Errores

Estado	Tipo	Cuándo
404	not-found	No existe esa variante en esta cuenta.

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

Actualizar una variante

PATCH/v1/variants/{id}

Fija su precio, las unidades compradas por venta, su peso o la variante de la tienda a la que corresponde. Envía solo lo que cambia.

Alcanceproducts:write

Parámetros de ruta

idstringobligatorio: El id de la variante.

Cuerpo

pricemoney: Opcional. Tu precio de venta.
unitsinteger: Opcional. De 1 a 50.
weight_ginteger: Opcional. Peso empacado de una unidad, en gramos.
external_variant_idstring|null: Opcional. Vincúlala a una variante de tu tienda, o null para desvincularla.

Errores

Estado	Tipo	Cuándo
404	not-found	No existe esa variante en esta cuenta.
409	invalid-state	Esa variante de la tienda ya corresponde a otro 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"
}