$0 as a regular renewal.
Paying in advance doesn’t decide whether the subscription renews afterward. To sell periods that end on their own, combine it with cancelAtPeriodEnd: true, described in One-Time Payments.
Charge several periods in the first payment
checkoutUrl. The first payment covers 3 periods of the price’s interval, including the current one: 3 months on a monthly price, 3 quarters on a quarterly one.
prepaidPeriods above 1 requires a paid recurring price. One-time prices and free plans return 400 validation_error with param: "prepaidPeriods".
Add periods to an existing subscription
checkoutUrl to the customer. It opens a hosted checkout for those periods.
The subscription status decides what
periods means:
A
pending_payment subscription that already paid and is awaiting a renewal returns 409. A canceled subscription also returns 409; to bring the customer back, create a new subscription with prepaidPeriods.
If the customer already generated an OXXO voucher for the pending checkout, Commet cancels it with the provider first. To apply an Offer to a pending subscription, send offerId when creating the subscription, or assign it with PUT /subscriptions/{id}/offer before or after this call: the checkout prices each paid period with that Offer.
Commet voids an unpaid link and emits invoice.voided when you create a new link, the plan or billing interval changes (immediately or as scheduled), or the subscription is paused, canceled immediately, or ends, including when failed payment retries cancel it. If the customer pays an OXXO voucher from a voided link, Commet refunds it automatically.
How each period is priced
Each period costs the price of the subscription’s interval for the buyer’s country and currency, minus the discount of the Offer phase that applies to that period.PUT /v1/subscriptions/{id}/offer to a subscription with paid periods left starts at the first renewal that charges, after the last paid period.
Card Promotions behave as on any subscription. Promo Codes do too, with two exceptions:
- A link that adds periods to an active subscription keeps the price it was created with, so a Promo Code entered there is rejected with “Promo codes can’t be used on a link that adds billing periods”.
- A trial Promo Code entered on a checkout that pays several periods or on a one-time purchase is rejected with “Trial codes can’t be used when paying in advance”.
Offers billed on another interval
An Offer with a phase billed on a different interval than the subscription, such as$5/month for 3 months on a yearly price, can’t combine with paying in advance. These requests return 400 validation_error:
A Promo Code for that Offer entered on a prepaid checkout is rejected with “This promo code can’t be used when paying several billing periods in advance”.
What the customer sees at checkout
On a link that adds periods to an active subscription, the label follows whether the subscription renews, not the method chosen in that checkout. An OXXO payment on a card subscription shows
then ….
End OXXO subscriptions after their paid periods
When a subscription is paid with OXXO and has no other saved payment method, Commet schedules its cancellation at the end of its paid periods.- The API shows
cancelAtPeriodEnd: trueandcancellation.effectiveAtright after the payment. subscription.updatedandsubscription.cancellation_scheduledfire, witheffectiveAtat the end of the paid periods andcancelReason: null.- The subscription isn’t renewed or charged, and
subscription.canceledfires when it ends.
POST /v1/subscriptions/{id}/payment-method/update) or Keep subscription in the Customer Portal. The subscription then renews normally with that card.
POST /v1/subscriptions/{id}/uncancel without a saved card returns 409 subscription_uncancel_failed.
Track paid periods after payment
currentPeriodstays one billing period.nextBillingDateis the next real charge, after the last paid period.- Each paid period renews with a paid
$0invoice, with no charge and no payment link, also for OXXO. - Features, credits, and balances reset on their usual schedule.
payment.receivedandsubscription.updated: the periods were paid.invoice.created: a paid period renewed with a$0invoice.invoice.voided: an unpaid link was voided.subscription.canceled: a one-time purchase or an OXXO subscription without a card ended.
Cancel, pause, or change plan
- Cancel: paid periods aren’t refunded, and a scheduled cancellation takes effect after the last paid period.
- Pause: rejected while paid periods remain.
- Plan or billing interval change: unused paid periods become Customer Credits at the price paid.
Pay in advance from the Dashboard
Open the subscription detail, choose Pay in advance, enter the number of periods, and choose Copy payment link. The field is labeled with the unit of the subscription’s interval, such as Months or Quarters. Send the copied link to the customer. The subscription detail shows Paid through with the date the paid periods end.Limitations
prepaidPeriodsandperiodsaccept1to60for every interval.- Only paid recurring prices. One-time prices and free plans return
400. - Free trials don’t combine with
prepaidPeriodsabove1or withcancelAtPeriodEnd. - Usage overage, seats, and add-ons aren’t prepaid: they’re billed on their usual schedule, and a renewal with a non-zero total follows the normal payment path.