Pagar por adelantado

Pagar por adelantado permite que un cliente cubra varios períodos de cobro de una suscripción en un solo pago, con tarjeta, OXXO o cualquier otro método del checkout. Funciona con precios semanales, mensuales, trimestrales, semestrales y anuales. El intervalo nunca cambia: cada período pagado se renueva a $0 como una renovación normal. Pagar por adelantado no decide si la suscripción se renueva después. Para vender períodos que terminan solos, combínalo con cancelAtPeriodEnd: true, descrito en Pagos únicos.

Cobrar varios períodos en el primer pago

Las pruebas gratuitas no se combinan con el pago por adelantado. Con prepaidPeriods mayor que 1 o cancelAtPeriodEnd: true, una prueba explícita (customTrialDays, una Offer con prueba o un Promo Code con prueba) devuelve 400, y se omite la prueba introductoria automática del plan.

curl -X POST https://commet.co/api/v1/subscriptions \
  -H "x-api-key: $COMMET_API_KEY" \
  -H "commet-version: 2026-08-27" \
  -H "Content-Type: application/json" \
  -d '{"customerId":"user_123","planId":"pln_xxx","prepaidPeriods":3}'

Redirige al cliente a checkoutUrl. El primer pago cubre 3 períodos del intervalo del precio, incluido el actual: 3 meses con un precio mensual, 3 trimestres con uno trimestral.

Parámetro	Tipo	Requerido	Descripción
`prepaidPeriods`	`integer`	No	Total de períodos de cobro que cubre el primer pago, incluido el actual. De `1` a `60`. Por defecto: `1`
`cancelAtPeriodEnd`	`boolean`	No	`true` termina la suscripción después de su último período pagado, sin renovación. Consulta Pagos únicos

prepaidPeriods mayor que 1 requiere un precio recurrente pago. Los precios de pago único y los planes gratuitos devuelven 400 validation_error con param: "prepaidPeriods".

Agregar períodos a una suscripción existente

curl -X POST https://commet.co/api/v1/subscriptions/sub_xxx/prepaid-periods \
  -H "x-api-key: $COMMET_API_KEY" \
  -H "commet-version: 2026-08-27" \
  -H "Content-Type: application/json" \
  -d '{"periods":3}'

Envía al cliente el checkoutUrl devuelto. Abre un checkout alojado para esos períodos.

Parámetro	Tipo	Requerido	Descripción
`periods`	`integer`	Sí	Períodos de cobro a pagar. De `1` a `60`. Su significado depende del estado de la suscripción
`offerId`	`string`	No	Offer que se aplica desde el primer período agregado durante toda su duración configurada. Solo suscripciones activas
`successUrl`	`string`	No	A dónde llega el cliente después de pagar

El estado de la suscripción define qué significa periods:

Estado	`periods`	El link nuevo
`active`	Períodos que se agregan después del último período pagado, con precio en la moneda de la suscripción	Reemplaza cualquier link anterior que no se haya pagado
`pending_payment`, antes de su primer pago	Total de períodos que cubre el primer pago, incluido el primero	Reemplaza el link de checkout pendiente

Una suscripción pending_payment que ya pagó y espera una renovación devuelve 409. Una suscripción cancelada también devuelve 409; para que el cliente vuelva, crea una suscripción nueva con prepaidPeriods. Si el cliente ya generó un voucher de OXXO para el checkout pendiente, Commet primero lo cancela con el proveedor. Para aplicar una Offer a una suscripción pendiente, envía offerId al crear la suscripción o asígnala con PUT /subscriptions/{id}/offer antes o después de esta llamada: el checkout cobra cada período pagado con esa Offer. Commet anula un link sin pagar y emite invoice.voided cuando creas un link nuevo, cambia el plan o el intervalo de cobro (en el momento o de forma programada), o la suscripción se pausa, se cancela de inmediato o termina, incluso cuando la cancelan los reintentos de pago fallidos. Si el cliente paga un voucher de OXXO de un link anulado, Commet lo reembolsa automáticamente.

Respuesta	Causa
`400 validation_error`	El precio es de pago único o el plan es gratuito
`400 validation_error`	La Offer de `offerId` tiene prueba gratuita, o se envió `offerId` para una suscripción `pending_payment`. `param` es `offerId`
`400 validation_error`	Una Offer cobra en otro intervalo. Consulta Offers que cobran en otro intervalo
`400 validation_error`	El total queda por debajo del cobro mínimo, por ejemplo con una Offer del 100%. `param` es `offerId` si enviaste una, o `periods` si no. El link anterior sin pagar sigue disponible para pagar
`409 invalid_subscription_status`	La suscripción no está `active` ni espera su primer pago, tiene una prueba gratuita o tiene una pausa programada
`409 charge_in_progress`	No se pudo cancelar un pago del link que se reemplaza, por ejemplo un voucher de OXXO ya generado

Cómo se calcula el precio de cada período

Cada período cuesta el precio del intervalo de la suscripción para el país y la moneda del comprador, menos el descuento de la fase de la Offer que corresponde a ese período.

Plan: $10/mes
Offer: 50% de descuento por 2 meses
Períodos: 3

Período 1 → $5
Período 2 → $5
Período 3 → $10
Pago → $20

En el primer pago, la moneda y el precio por país se resuelven en el checkout, como en cualquier suscripción. Las Offers duran toda su duración configurada desde el primer período pagado. Una Offer asignada con PUT /v1/subscriptions/{id}/offer a una suscripción con períodos pagados por usar empieza en la primera renovación que cobra, después del último período pagado. Las Card Promotions funcionan como en cualquier suscripción. Los Promo Codes también, con dos excepciones:

Un link que agrega períodos a una suscripción activa mantiene el precio con el que se creó, así que un Promo Code ingresado ahí se rechaza con el mensaje “Promo codes can’t be used on a link that adds billing periods”.
Un Promo Code de prueba gratis ingresado en un checkout que paga varios períodos o en una compra única se rechaza con el mensaje “Trial codes can’t be used when paying in advance”.

Offers que cobran en otro intervalo

Una Offer con una fase que cobra en un intervalo distinto al de la suscripción, como $5/mes por 3 meses sobre un precio anual, no se combina con el pago por adelantado. Estos requests devuelven 400 validation_error:

Request	`param`
`POST /v1/subscriptions` con `prepaidPeriods` mayor que `1` y esa Offer por `offerId` o `promoCode`	`prepaidPeriods`
`POST /v1/subscriptions/{id}/prepaid-periods` con ese `offerId`, o con esa Offer ya asignada o en curso	`offerId` si lo enviaste
`PUT /v1/subscriptions/{id}/offer` sobre una suscripción con períodos pagados sin usar o un link sin pagar	`offerId`

Un Promo Code de esa Offer ingresado en un checkout de pago por adelantado se rechaza con el mensaje “This promo code can’t be used when paying several billing periods in advance”.

Qué ve el cliente en el checkout

Compra	El checkout muestra
Se renueva después de los períodos pagados	`3 meses · después sigue a $10.00/mes` o `2 trimestres · después sigue a $30.00/trim`
Compra única, suscripción con fin programado, o primer pago con un método que no puede renovarse (OXXO)	`3 meses · pago único, no se renueva`

En un link que agrega períodos a una suscripción activa, el texto depende de si la suscripción se renueva, no del método elegido en ese checkout. Un pago con OXXO sobre una suscripción con tarjeta muestra después sigue a ….

Terminar suscripciones pagadas con OXXO al final de sus períodos

Cuando una suscripción se paga con OXXO y no tiene otro método de pago guardado, Commet programa su cancelación al final de sus períodos pagados.

La API muestra cancelAtPeriodEnd: true y cancellation.effectiveAt justo después del pago.
Se disparan subscription.updated y subscription.cancellation_scheduled, con effectiveAt al final de los períodos pagados y cancelReason: null.
La suscripción no se renueva ni se cobra, y subscription.canceled se dispara cuando termina.

Para conservarla, el cliente agrega una tarjeta con el link para actualizar el método de pago (POST /v1/subscriptions/{id}/payment-method/update) o con Mantener suscripción en el Portal del Cliente. La suscripción se renueva normalmente con esa tarjeta. POST /v1/subscriptions/{id}/uncancel sin una tarjeta guardada devuelve 409 subscription_uncancel_failed.

Seguir los períodos pagados después del pago

currentPeriod sigue siendo de un período de cobro.
nextBillingDate es el próximo cobro real, después del último período pagado.
Cada período pagado se renueva con un recibo pagado de $0, sin cobro ni link de pago, también con OXXO.
Las features, los créditos y los balances se reinician en su calendario habitual.

El pago por adelantado usa eventos de webhook existentes:

payment.received y subscription.updated: se pagaron los períodos.
invoice.created: un período pagado se renovó con un recibo de $0.
invoice.voided: se anuló un link sin pagar.
subscription.canceled: terminó una compra única o una suscripción pagada con OXXO sin tarjeta.

Cancelar, pausar o cambiar de plan

Cancelar: los períodos pagados no se reembolsan, y una cancelación programada se hace efectiva después del último período pagado.
Pausar: se rechaza mientras queden períodos pagados.
Cambiar de plan o de intervalo de cobro: los períodos pagados sin usar se convierten en Customer Credits al precio pagado.