# Recurring Add-ons

This guide extends [Add-ons](/docs/core/add-ons) with the recurring recurrence type, which renews an add-on's allowances automatically instead of applying them once.

<Note type="warning">

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

</Note>

## 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. |

## Configuration

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.

<Note type="info">

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

</Note>

## 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:

1. The user gets a set amount of data with no speed limit, for example 3GB.
2. After that, they get a set amount of data at a lower speed, for example 10GB more at 256 kbps.
3. 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.

On p15, the throttled speed can be 128 kbps, 256 kbps, 512 kbps, 1 Mbps, 3 Mbps or 5 Mbps.

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.