Saltar al contenido principal
Un Promo Code es un canal de distribución. La Offer referenciada contiene el descuento; el código controla quién puede canjearlo y cuándo.

Crear una Offer compatible

Un Promo Code puede referenciar cualquier Offer: fases ordenadas percentage, amount_off o fixed_price donde solo la última puede no tener vencimiento.
Una fase 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 Promo Code contiene:
  • 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.
Un cliente califica para un código de primera compra mientras no tenga recibos pagados por más de $0 ni una suscripción 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 fuente promo_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.
Un trial sin método de pago no tiene checkout, así que no puede empezar con un promo code.

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.
Desde un plan gratuito, el código abre el checkout con el descuento aplicado y cuenta el canje cuando se paga. Los cambios programados rechazan un promo code con offer_not_applicable.

Motivos de rechazo

Un código rechazado devuelve 400 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.
El checkout también rechaza un total positivo por debajo del cobro mínimo de la moneda.

Códigos gestionados por una integración

Los códigos creados por una integración, como Dub, tienen managedBy. Cambiar sus restricciones devuelve 409 managed_by_integration; activarlos y desactivarlos sigue funcionando.