Variantes y precios

Crea el «Polo de algodón» con Color y Talla, una variante por combinación, y cambia sus precios uno a uno o en lote.

Requisitos

• Un token de Admin en ECOMIQ_TOKEN. Ver Inicio rápido.
• Los permisos catalog:create, catalog:update y catalog:delete, según lo que hagas.

Crea el producto

Declara las opciones en options y una variante por combinación en variants.

• Cada variante indica en options su valor por opción, por nombre o por key.
• Las opciones que no existen en la tienda se crean.
• price, compareAtPrice y costPrice del producto se aplican a las variantes que no traen los suyos.
• Con varias variantes, marca una sola con isDefault: true.

{
  "name": "Polo de algodón",
  "description": "Polo de algodón pima para uso diario.",
  "status": "draft",
  "price": 89,
  "compareAtPrice": 99,
  "costPrice": 45,
  "options": [
    { "name": "Color", "key": "color", "values": ["Azul", "Negro"] },
    { "name": "Talla", "key": "talla", "values": ["S", "M", "L"] }
  ],
  "variants": [
    {
      "name": "Azul / S",
      "sku": "POL-001-AZ-S",
      "options": { "Color": "Azul", "Talla": "S" }
    },
    {
      "name": "Azul / M",
      "sku": "POL-001-AZ-M",
      "options": { "Color": "Azul", "Talla": "M" },
      "isDefault": true
    },
    {
      "name": "Negro / S",
      "sku": "POL-001-NG-S",
      "options": { "Color": "Negro", "Talla": "S" }
    },
    {
      "name": "Negro / M",
      "sku": "POL-001-NG-M",
      "options": { "Color": "Negro", "Talla": "M" }
    }
  ]
}

curl -X POST https://api.ecomiq.pe/api/v1/catalog/products \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  --data @producto.json

{
  "id": "7204558912004325302",
  "name": "Polo de algodón",
  "slug": "polo-de-algodon",
  "status": "draft",
  "variants": [
    {
      "id": "7204558912004325377",
      "name": "Azul / M",
      "sku": "POL-001-AZ-M",
      "isDefault": true,
      "price": 89,
      "compareAtPrice": 99,
      "costPrice": 45,
      "options": [
        { "name": "Color", "key": "color", "value": "Azul" },
        { "name": "Talla", "key": "talla", "value": "M" }
      ],
      "status": "active"
    }
  ]
}

La API responde 201 con el producto y sus variantes. Guarda el id de cada variante junto a su SKU; los IDs son strings.

El producto queda en borrador. Para activarlo, envía { "status": "active" } a PATCH /v1/catalog/products/{productId}.

Agrega una variante

Agrega la talla L en azul. Si omites price o compareAtPrice, se usan los del producto. costPrice no se hereda: envíalo si lo usas.

curl -X POST https://api.ecomiq.pe/api/v1/catalog/products/7204558912004325302/variants \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Azul / L",
    "sku": "POL-001-AZ-L",
    "price": 89,
    "compareAtPrice": 99,
    "costPrice": 45,
    "options": { "Color": "Azul", "Talla": "L" }
  }'

{
  "id": "7204558912004325381",
  "productId": "7204558912004325302",
  "name": "Azul / L",
  "sku": "POL-001-AZ-L",
  "status": "active",
  "price": 89,
  "compareAtPrice": 99,
  "costPrice": 45,
  "currency": "PEN",
  "options": [
    { "name": "Color", "key": "color", "value": "Azul" },
    { "name": "Talla", "key": "talla", "value": "L" }
  ]
}

La API responde 201. Un SKU repetido o una combinación de opciones que ya tiene otra variante responde 409.

Cambia el precio de una variante

PATCH /v1/catalog/variants/{variantId} cambia solo los campos que envías. Aquí, Azul / M pasa a 85 y su costo a 42.

curl -X PATCH https://api.ecomiq.pe/api/v1/catalog/variants/7204558912004325377 \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "price": 85, "compareAtPrice": 99, "costPrice": 42 }'

La respuesta 200 trae la variante actualizada.

• Si compareAtPrice no supera price, se elimina.
• null en compareAtPrice o costPrice lo elimina.
• Cada cambio de price o compareAtPrice queda en el historial de precios.
• El price del producto es el de su variante activa más barata.

La misma ruta cambia también name, sku, barcode y status.

Para editar variantes desde PATCH /v1/catalog/products/{productId}, ver Productos: ahí null no borra precios y se usan clearCompareAtPrice y clearCostPrice.

Cambia precios en lote

POST /v1/catalog/products/batch/prices recibe hasta 100 filas en items. Cada fila elige su destino con targetKind:

• product: todas las variantes del producto, por su id.
• variant: una variante, por su id.
• sku: una variante, por SKU, sin distinguir mayúsculas.

Este ejemplo pone en oferta las tres tallas azules.

curl -X POST https://api.ecomiq.pe/api/v1/catalog/products/batch/prices \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "promotionStart",
    "items": [
      { "targetKind": "sku", "target": "POL-001-AZ-S", "price": 79, "compareAtPrice": 99 },
      { "targetKind": "sku", "target": "POL-001-AZ-M", "price": 79, "compareAtPrice": 99 },
      { "targetKind": "sku", "target": "POL-001-AZ-L", "price": 79, "compareAtPrice": 99 }
    ]
  }'

{
  "results": [
    { "index": 0, "id": null, "status": "updated", "errors": [] },
    { "index": 1, "id": null, "status": "updated", "errors": [] },
    { "index": 2, "id": null, "status": "updated", "errors": [] }
  ]
}

200 devuelve results[] en el orden recibido. Revisa las filas failed: las demás se aplican igual. Con targetKind: sku, id es null; usa index para ubicar la fila.

Para más filas, envía filters en lugar de items, con price, compareAtPrice o clearCompareAtPrice. Responde 202 con una operación.

• Omite price para conservar el precio actual.
• clearCompareAtPrice: true elimina el precio de comparación.
• reason queda en el historial; por defecto es bulkEdit.
• costPrice no se cambia en lote: usa PATCH en cada variante.

Elimina una variante

Elimina Negro / S. La API responde 204, sin cuerpo.

curl -X DELETE https://api.ecomiq.pe/api/v1/catalog/variants/7204558912004325379 \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

Para ocultar una variante sin eliminarla, envía { "status": "inactive" } con PATCH. Solo las variantes activas cuentan para el precio y el stock del producto.

Crea una lista de precios

Una lista de precios fija el precio de variantes concretas. El carrito usa ese precio mientras la lista está activa y vigente.

• items fija unitPrice por variante.
• breaks cambia el precio desde minQuantity unidades, con un mínimo de 2.
• validFrom y validTo limitan la vigencia.
• Con customerId, la lista aplica solo a ese cliente.

curl -X POST https://api.ecomiq.pe/api/v1/catalog/price-lists \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mayoristas",
    "currency": "PEN",
    "isActive": true,
    "priority": 1,
    "scope": "product",
    "productId": "7204558912004325302",
    "items": [
      {
        "variantId": "7204558912004325377",
        "unitPrice": 70,
        "breaks": [{ "minQuantity": 12, "unitPrice": 65 }]
      },
      { "variantId": "7204558912004325380", "unitPrice": 70 }
    ]
  }'

{
  "id": "7204558912004321823"
}

Si varias listas cubren una variante, gana la del cliente y luego la de mayor priority. Para cambiar una lista, envíala completa a PUT /v1/catalog/price-lists/{priceListId}. Reemplaza su contenido y responde 204.

Errores

Siguientes pasos

• Inventario: carga el stock de cada variante.
• Variantes: operaciones y campos.
• Listas de precios: crea, lista y actualiza listas.