Crear una Offer compatible
Un Promo Code puede referenciar cualquier Offer: fases ordenadaspercentage, amount_off o fixed_price donde solo la última puede no tener vencimiento.
fixed_price de 0, Free cycles en el dashboard, crea un código que regala ciclos de facturación. El checkout guarda la tarjeta y liquida el recibo en $0 sin cobrar.
Crear el código
- el código visible para el cliente;
- las restricciones opcionales por plan e intervalo;
- el límite de canjes;
- el vencimiento y estado activo;
firstPurchaseOnly, que limita el código a la primera compra del cliente. Por defecto,false.
active o past_due en un plan pago. Un cliente en período de prueba califica.
Actualizar la Offer cambia los canjes futuros de los códigos que la referencian. Cada checkout completado cuenta como un canje y guarda una Offer Application inmutable con las fases aceptadas en ese momento. La edición no cambia los canjes anteriores ni sus renovaciones.
Los clientes fijados a una versión anterior a 2026-07-24 reciben solo la primera fase en los campos de descuento heredados del Promo Code cuando es percentage o amount_off. Los códigos que empiezan con fixed_price no se pueden representar y no aparecen en esos endpoints antiguos. La API actual de Offers permite consultar la secuencia completa.
Comportamiento en checkout
El cliente ingresa el código durante checkout. Commet valida el código, resuelve la Offer referenciada en la moneda del checkout y registra una Offer Application con fuentepromo_code.
Cuando el precio tiene un trial que requiere método de pago, el cliente puede ingresar el código en el checkout de la prueba. La prueba empieza sin cobro y el descuento empieza con el primer recibo después de ella. El canje se cuenta una sola vez cuando se completa el checkout. Las renovaciones no suman canjes.
Si aplica una Introductory Offer automática elegible, el código se rechaza con intro_offer_active. Tampoco puede combinarse un Promo Code con un offerId explícito.
Aplicar un código en un cambio de plan
changePlan y previewChange aceptan promoCode en los cambios inmediatos. La vista previa cotiza lo mismo que cobra el cambio.
offer_not_applicable.
Motivos de rechazo
Un código rechazado devuelve400 validation_error con param: "promoCode" y el motivo en details.reason:
not_found: no existe un código con ese texto.inactive: el código está desactivado.expired: pasó la fecha de vencimiento.max_redemptions_reached: se alcanzó el límite de canjes.first_purchase_only: el cliente ya pagó o tiene una suscripción paga.already_redeemed: el cliente ya canjeó el código.plan_not_eligible: el código está restringido a otros planes.billing_interval_not_eligible: el código está restringido a otro intervalo de cobro.intro_offer_active: aplica una Introductory Offer.
Códigos gestionados por una integración
Los códigos creados por una integración, como Dub, tienenmanagedBy. Cambiar sus restricciones devuelve 409 managed_by_integration; activarlos y desactivarlos sigue funcionando.