Usar productos y precios

Un producto describe qué vendes. Sus planes definen cómo cobras y sus precios especifican el importe en cada moneda. Elige un precio del catálogo para vender esa oferta mediante el checkout alojado.

Por ejemplo, un curso en línea es un producto. Puedes ofrecerlo como compra única o suscripción mensual, cada una con sus propios precios.

Antes de empezar

Configura el producto, sus planes y sus precios en el Panel de Pharos. Usa una clave de API de la cuenta y el entorno donde está configurada la oferta. Tu backend necesita permiso de lectura para consultar el catálogo y de escritura para crear una sesión de checkout. Mantén la clave en tu servidor.

Entender productos, planes y precios

Producto: qué vendes

El producto identifica el bien o servicio: el nombre del curso, su descripción y si está activo. Un mismo curso puede tener varias opciones de pago sin convertirse en varios productos.

Plan: cómo cobras

Elige la opción que corresponde a tu oferta. Un plan de pago único cobra una vez. Un plan de suscripción define cobros recurrentes y cualquier período de prueba configurado. Un plan gratuito representa una oferta sin cargo.

Para el curso, elige el plan de pago único para una compra o el plan de suscripción mensual para acceso continuo. Estas opciones dependen de los planes que hayas configurado.

Precio: cuánto y en qué moneda

Cada plan puede tener precios en distintas monedas. Un precio en USD y otro en ARS son importes configurados por separado para la misma opción de pago. Solicitar una moneda no convierte el importe de la otra.

Elegir una oferta disponible

Empieza por consultar tus productos. Luego elige el plan de la compra y un precio en la moneda del cliente.

Usa un producto activo con un plan y un precio que no estén archivados. Una referencia de producto guardada puede devolver elementos inactivos o archivados. Encontrarla en el catálogo no confirma que esté disponible para una nueva compra.

Comprueba los planes y precios predeterminados antes de usarlos. Puede no haber uno configurado o quedar excluido por tus filtros de moneda o archivo. Elige una opción disponible que coincida con la oferta, sin seleccionar automáticamente el primer resultado.

Si el plan no tiene precio en la moneda solicitada, ofrece otra moneda configurada o muestra la oferta como no disponible. El importe del catálogo no es una cotización final: los descuentos configurados y las promociones aplicables al cliente o la tarjeta afectan el importe en checkout.

Llevar al cliente a checkout

Para una oferta reutilizable, usa un enlace de pago. Configura la oferta una vez y comparte su URL de checkout.

Para un carrito construido por tu aplicación, usa Cart Checkout. Tu backend envía el precio elegido al crear una sesión de checkout y lleva al cliente a la URL devuelta. Este flujo también admite precios en línea para importes contextuales fuera del catálogo.

Mantén una relación entre la oferta de tu aplicación y su producto, plan y precio en Pharos. Verifica el webhook de compra firmado antes de entregar la compra; una redirección exitosa por sí sola no confirma el pago.

Detalles de implementación

Consulta solicitudes, respuestas JSON, campos, consultas por lote, paginación y manejo de errores en la referencia de Productos.

Configurar cuotas por precio

Activá Permitir cuotas para este precio para ingresar las cantidades. El campo queda oculto al desactivarlo y el precio permite un pago.

Configurá las cuotas permitidas en cada precio del producto, por ejemplo 1, 3, 6 para ARS y 1 para USD. Siempre se incluye un pago. En suscripciones, esta configuración corresponde solo a un cargo pagado durante checkout; las renovaciones y los cobros después de una prueba gratuita se hacen en un pago. El checkout recurrente sigue ofreciendo un pago hasta que su ruta esté verificada para financiar y guardar la tarjeta en conjunto.

La API de productos devuelve productPlans[].prices[].allowedInstallments. Al crear una Checkout Session, usá el priceId guardado para heredar esa política. No necesitás volver a enviar las cuotas. Los precios creados directamente con priceData permiten un pago.

{
  "id": "price_example",
  "currency": "ARS",
  "price": "120000.00",
  "allowedInstallments": [1, 3, 6]
}

Si un carrito combina precios que permiten [1, 3, 6] y [1, 3], checkout ofrece las cantidades comunes [1, 3], sujetas a la disponibilidad de la tarjeta. Una sesión o un Payment Link puede restringir esas opciones con allowedInstallments, pero no agregar cuotas que los precios no permiten. Omití el campo o usá null para heredar. Al actualizar, omitilo para conservar la restricción o enviá null para quitarla. Las respuestas distinguen las opciones efectivas en allowedInstallments de la restricción opcional en installmentRestriction.

Estas cantidades no garantizan cuotas sin interés. Checkout confirma disponibilidad, importe por cuota, total financiado y recargos con la tarjeta elegida. Editar un precio afecta sesiones nuevas; las existentes conservan sus condiciones. Los Payment Links existentes heredan la política actual del catálogo. Los precios existentes comienzan con un pago hasta que configures sus cuotas.

Mostrar el precio con promociones antes del checkout

Consulta GET /api/v1/products?currency=ARS&includePricing=true o agrega includePricing=true al consultar un producto. Cada precio activo incluye pricing. Muestra pricing.totalAmount y utiliza pricing.listAmount como precio de lista. price y discount conservan su significado actual.

Pharos selecciona promociones automáticas con las mismas reglas de elegibilidad, acumulación y redondeo del checkout. appliedPromotions explica los descuentos incluidos. conditionalPromotions describe beneficios visibles que requieren tarjeta, cuotas, identidad del cliente o confirmación de financiación; no reducen el total mostrado. Las promociones ocultas pueden aplicar y aparecen en el desglose aplicado.

El resultado corresponde a una unidad de ese precio, no a un carrito combinado. En suscripciones describe el primer período facturable, no el importe a pagar durante un trial gratuito. La duración se devuelve como FIRST_PAYMENT, CYCLES o FOREVER, con durationCycles cuando corresponde. Los productos inactivos y planes o precios archivados devuelven pricing: null.

Al comprar, crea la sesión con el priceId original y promotionMode: "AUTOMATIC". No envíes un importe inline rebajado ni elijas IDs de promociones:

{"mode":"PAYMENT","lineItems":[{"priceId":"price_example","quantity":1}],"promotionMode":"AUTOMATIC","successUrl":"https://example.com/purchase-complete"}

Para promociones con límite por cliente, vincula el Customer mediante customer al crear la sesión. Un correo por sí solo no confirma la elegibilidad.

Utiliza mode: "SUBSCRIPTION" para precios recurrentes. Crear la sesión requiere permiso WRITE y un Idempotency-Key; consultar el catálogo requiere READ. Conserva las claves de API en tu backend.

evaluatedAt indica cuándo se calculó el importe; no garantiza el precio ni indica un vencimiento. La consulta no crea sesiones ni reserva usos o presupuesto. Si una promoción vence o se agota antes de comprar, la sesión recalcula el precio vigente. Muestra el total de la sesión antes de pagar. La sesión conserva sus campañas candidatas al crearse; no incorpora campañas nuevas después. Sin includePricing, Products conserva su respuesta actual. Sin promotionMode, la creación mantiene el comportamiento explícito de promotionIds.