Skip to main content
A subscription automates future payments within the boundaries of a mandate. When subscription_options is provided on a first_in_series session, the platform schedules and executes recurring collections automatically. The mandate is the consent ceiling; the subscription runs within it. Subscriptions are valid only on scheduled and installment mandates, which carry a consented cadence the subscription engine uses to schedule collections. They are not available on on_demand mandates: a subscription needs a cadence, and on_demand has none. For when to pick each shape, see Recurring Payments.
Subscription automation for installment mandates with terms.type: fixed is coming soon.Today, each installment in a fixed plan must be initiated via next_in_series sessions on the due dates defined in items. Subscription support is available now for periodic terms.
Providing subscription_options is optional.Omitting it creates the mandate but leaves scheduling to the merchant, who must initiate each next_in_series payment manually.An empty subscription_options is valid and creates a subscription with all properties inherited or defaulted from the mandate: active_period inherits from mandate_options.validity_period, amount infers from mandate_options.amount or the original session amount, and scheduled_time defaults to 00:00.If the mandate has no validity_period, the subscription runs indefinitely.
A subscription’s active_period must fall within the mandate’s validity_period.The platform will not execute a payment that would violate any mandate constraint, regardless of what the subscription schedules.

​
Active Period

Defines the date range within which the subscription is active. Payments are only scheduled within this window. A subscription active throughout 2026:
If start_date is omitted, the subscription starts immediately (or inherits from mandate_options.validity_period.start_date). If end_date is omitted, it runs indefinitely (or inherits from mandate_options.validity_period.end_date). The active period must fall within mandate_options.validity_period. The mandate remains the authorisation ceiling and cannot be exceeded.

​
Amount

The fixed amount in the smallest currency unit collected for each scheduled payment. Collecting 20.00 ZAR on each scheduled payment:
If omitted, the amount is inferred in order from: mandate_options.amount (if a fixed amount), then the original session amount.

​
Recurrence

The payment cadence is defined in mandate_options, not in subscription_options. The recurrence is the customer’s consented cadence; the subscription engine uses it to schedule collections. For scheduled mandates, recurrence is at mandate_options.recurrence. For installment mandates with terms.type: periodic, it is at mandate_options.terms.recurrence. See Mandates: Recurrence for the full reference and examples.

​
Scheduled Time

The time of day at which scheduled collections are executed. Specified in 24-hour HH:MM format and evaluated in the timezone set by mandate_options.timezone. Defaults to 00:00 if not specified. Collections executed at 9:00 AM each scheduled day:
For full configuration examples, see Subscription Examples.