Productos

Un producto sin variantesCopiar enlace

{
  "name": "Curso de fotografía",
  "currency": "USD",
  "amount": 2500
}

Sin variantes, amount es obligatorio. stock: null representa existencias ilimitadas y stock: 0, un producto agotado.

Un producto con variantesCopiar enlace

{
  "name": "Camiseta",
  "category": "physical",
  "currency": "USD",
  "fulfillmentMethods": ["pickup"],
  "variants": [
    { "name": "M", "amount": 2000, "stock": 10, "isDefault": true },
    { "name": "L", "amount": 2200, "stock": 8 }
  ]
}

Cada variante tiene su precio y sus existencias. Con variantes, no envíes un precio ni un stock independiente para el producto padre. La moneda y el comportamiento fiscal pertenecen al producto.

Las existencias se reservan al iniciar el pago, no al abrir el checkout. Un reembolso no repone unidades automáticamente.

Tu clave para el productoCopiar enlace

lookupKey es tu propio nombre para el producto (camiseta): minúsculas, números, _ y -, empezando por una letra, y único entre tus productos de cada entorno (si no, lookup_key_in_use). Encuéntralo con GET /v1/products?lookupKey=camiseta y cámbialo o quítalo (null) con PATCH. A diferencia de metadata, es público: cada ítem del checkout en el navegador lo trae, para que tu checkout propio sepa qué vende sin guardar IDs.

Usa active: false para pausar ventas y true para reanudarlas. Eliminar es definitivo: el producto sale de las listas (?deleted=true las muestra) con sus variantes y sus enlaces, queda con deletedAt y deletedBy, sigue consultable por su ID y su lookupKey queda libre. Las compras hechas no cambian y los checkouts abiertos se pueden pagar mientras queden unidades. No omitas variantes guardadas para quitarlas (variant_deletion_required): elimínalas.

Configura descuentos con cupones.

FotosCopiar enlace

Las fotos se suben desde el dashboard, en el editor del producto: hasta 8, la primera es la principal, y cada variante puede tener la suya. El producto las trae en images (id y url), en orden, y cada variante en imageId la que eligió (null muestra la principal). Las url son públicas y no cambian: una foto nueva tiene otra dirección, así que puedes guardarlas en caché sin vencimiento. Si no subes fotos, imageUrl sigue siendo la dirección que tu integración le dé al producto.