Skip to main content
A subscription with a trial is born trialing, bills nothing, and converts on its own when the trial ends.

​
Where the trial length comes from

The two doors do not read the same source. A price with trialPeriodDays: 14 gives 14 days of trial on the hosted page, and zero through the API if you omit trialDays. Set both if you use both doors.

​
During the trial

  • status: "trialing", trialStart and trialEnd set.
  • The current period is the trial: currentPeriodEnd = trialEnd. A 14-day trial on a monthly plan gives 14 days, not 14 + 30.
  • No invoice, no payment request.
  • You receive subscription.trial_ending at creation (API door only — the hosted page does not emit it). It is not a D-3 reminder: do not use it as one.
  • pause is refused during a trial. cancel is possible (see below).

​
When the trial ends

1

Conversion, within the hour

An hourly cron finds expired trials and moves the subscription to active. The paid period is anchored on trialEnd: currentPeriodStart = trialEnd, currentPeriodEnd = trialEnd + interval, trialConverted = true. No subscription.* webhook is emitted at that point.
2

First payment request, at the next 11:00 (Brazzaville)

The invoice for the first paid period is issued and a payment request is pushed to the customer’s default Mobile Money number. You receive invoice.finalized, then invoice.paid and payment.completed if the customer approves.
If that first request fails, the subscription stays active — it does not become past_due, and that invoice does not enter the automatic retries (it is a subscription_create invoice, not a subscription_cycle one). It stays open and payable through the emailed link; the cron will retry it on the next due date. Watch for invoice.finalized without invoice.paid within the day, and either point the customer to the link or retry with retry-payment.

​
Cancelling during a trial

Use cancelImmediately: true. An “at period end” cancellation during a trial sets cancelAt = trialEnd, but conversion runs hourly while scheduled cancellations only run at 03:00 UTC: the subscription would be converted and a payment request would go out before the cancellation applies.

​
Checking the trial state

GET /v1/subscriptions/{id} returns statistics.isInTrial and statistics.trialDaysRemaining, in addition to trialEnd.