Cupones
Descuentos por código para productos o para planes.
Cupones
{
"code": "PLUS50",
"percentOff": 50,
"appliesTo": "plans",
"plans": ["plan_0192…"],
"payments": 3,
"expiresAt": "2026-12-31T23:59:59-04:00"
}Un cupón es para productos o para planes (appliesTo), nunca para ambos. Con products o plans (IDs) se limita a esos; sin ellos vale para todos los de su tipo. En un carrito solo descuenta las líneas que cubre, y si no cubre ninguna el checkout lo rechaza con coupon_not_applicable.
Elige percentOff o amountOff, nunca ambos. Un descuento fijo exige currency, y un cupón con moneda solo aplica a precios en ella (coupon_currency_mismatch). Al crearlo se comprueba que los productos o planes existan y tengan esa moneda.
Pagos con descuento
En planes, payments es cuántos pagos de la suscripción descuenta, desde el primero que se cobra: 1 (por defecto) solo el primero, 3 los tres primeros y null todos. Si el plan tiene prueba gratis, el primer pago descontado es la primera renovación. Al cambiar a un plan que el cupón no cubre, las renovaciones de ese plan se cobran completas. En productos payments siempre es 1.
Condiciones
| Campo | Qué limita |
|---|---|
expiresAt | Hasta cuándo se puede aplicar. Una suscripción que ya lo tiene lo sigue usando. |
maxRedemptions | Cuántos pagos (checkouts y cobros) pueden usarlo. Una renovación que conserva el cupón de su suscripción no cuenta. |
minimumAmount | Subtotal mínimo del pedido, antes de descuentos e impuestos, en currency. |
oncePerCustomer | Cada cliente (por su correo) lo usa una vez. |
firstPurchaseOnly | Solo para clientes que nunca le han pagado al negocio: un plan gratis o una prueba no cuentan. |
oncePerCustomer y firstPurchaseOnly se comprueban cuando se conoce al cliente: al crear un checkout con customer y otra vez al pagar. Si al pagar el cliente no puede usarlo, el cupón se quita, el checkout se recalcula y el pago responde coupon_already_used o coupon_first_purchase_only para que el cliente vea el nuevo total antes de pagar.
Dónde se aplica
Tu integración aplica un cupón con coupon al crear el checkout o al cambiar de plan una suscripción. Tus clientes pueden escribirlo al pagar, en el checkout alojado (también el de un enlace o un cambio de plan) y en la página de un cobro, mientras tu negocio acepte cupones: es un ajuste de todo el negocio, en Configuración › Cobros › Cupones, activo por defecto. Con los cupones desactivados, solo tu integración los aplica, y quien ya tiene uno lo conserva.
| Código | Cuándo |
|---|---|
coupon_inactive, coupon_expired, coupon_exhausted | Desactivado, vencido o sin usos disponibles. |
coupon_not_applicable | No cubre lo que se compra. |
coupon_currency_mismatch | Los precios están en otra moneda. |
coupon_minimum_not_met | El pedido no llega a minimumAmount. |
coupons_not_allowed | Tu negocio no acepta cupones de sus clientes. |
| Método | Ruta | Acción |
|---|---|---|
| POST / GET | /v1/coupons | Crear / listar |
| GET / PATCH | /v1/coupons/:coupon | Consultar / actualizar |
| DELETE | /v1/coupons/:coupon | Eliminar |
Se actualizan el nombre, active, maxRedemptions (no menos que los usos que ya tiene) y expiresAt; el descuento y a qué aplica no cambian una vez creado.
Eliminar o desactivar
Desactivarlo (active: false) lo pausa: deja de aplicarse en compras nuevas y puedes reactivarlo. Eliminarlo (DELETE) es definitivo, aunque ya se haya usado: sale de las listas, su código queda libre para otro cupón y responde el cupón con deletedAt. En los dos casos conserva su historial de usos, y las suscripciones y los checkouts o cobros abiertos que ya lo tienen siguen con su descuento. Un cupón eliminado se consulta por su ID, ya no por su código, y no se puede modificar (coupon_deleted).