Recurring Add-ons

This guide extends Add-ons with the recurring recurrence type, which renews an add-on's allowances automatically instead of applying them once.

Recurring add-ons are enabled for your project by Gigs and require a network provider that supports add-on renewals.

Recurrence Types

Add-ons support two recurrence types, controlled by the recurrenceType field:

Recurrence	Behaviour
`oneTime`	A one-time purchase applied to the subscription for a single validity period.
`recurring`	Renews automatically at the start of each validity period, for a fixed number of periods.

A recurring add-on repeats its validity window a fixed number of times, for example 1GB per day for 7 days. Gigs sets the window and the number of periods when it creates the add-on for your project. Indefinite recurrence is not supported yet.

Each period lasts one validity window and rolls on the add-on's own schedule, starting from its activation and independent of the subscription period.

Renewals

Renewal is automatic. At the start of each period, the allowance is re-provisioned on the network and currentPeriod advances to the next period number. The subscription add-on stays active throughout. After the final period elapses, it transitions to ended.

Things to be aware of in the current implementation:

If billing is enabled for your project, a single invoice is generated when the subscription add-on is created. Renewals do not generate additional invoices.
Ending a recurring subscription add-on through the API takes effect immediately and cancels all future renewals.

To filter add-ons by recurrence, use the recurrenceType query parameter, e.g. ?recurrenceType=recurring.

Throttling

A recurring add-on can slow the user down instead of cutting them off once they've used the period's full-speed data, so they stay connected until the next period starts. In each period:

The user gets a set amount of data with no speed limit, for example 3GB.
After that, they get a set amount of data at a lower speed, for example 10GB more at 256 kbps.
When the next period starts, the user gets both amounts again in full. Data they didn't use doesn't carry over.

An add-on without throttling gives the user its allowance at full speed each period, and no more data until the next period starts.

Gigs sets up throttling when it creates the add-on for your project. Tell Gigs the lower speed and how much data the user gets at each speed, or that you don't want throttling.

Recurrence

Behaviour

oneTime

A one-time purchase applied to the subscription for a single validity period.

recurring

Renews automatically at the start of each validity period, for a fixed number of periods.

Configuration

Each period lasts one validity window and rolls on the add-on's own schedule, starting from its activation and independent of the subscription period.

Renewals

Things to be aware of in the current implementation:

If billing is enabled for your project, a single invoice is generated when the subscription add-on is created. Renewals do not generate additional invoices.

Ending a recurring subscription add-on through the API takes effect immediately and cancels all future renewals.

To filter add-ons by recurrence, use the recurrenceType query parameter, e.g. ?recurrenceType=recurring.

Throttling

A recurring add-on can slow the user down instead of cutting them off once they've used the period's full-speed data, so they stay connected until the next period starts. In each period:

The user gets a set amount of data with no speed limit, for example 3GB.

After that, they get a set amount of data at a lower speed, for example 10GB more at 256 kbps.

When the next period starts, the user gets both amounts again in full. Data they didn't use doesn't carry over.

An add-on without throttling gives the user its allowance at full speed each period, and no more data until the next period starts.

Gigs sets up throttling when it creates the add-on for your project. Tell Gigs the lower speed and how much data the user gets at each speed, or that you don't want throttling.