# Implement Unlimited Roaming
Travelers often don't know how much data a trip needs and will be frustrated when running out. Unlimited roaming gives them a fresh, high-speed data allowance every day of their trip and keeps them connected at a reduced speed when they use it up.
This guide shows you how to set up unlimited roaming with the Gigs API: find the right package, attach it to a subscription, and show your users where they stand each day.
## How unlimited roaming works
Unlimited roaming is a [recurring add-on][recurring-add-ons] that you attach to an existing subscription. A recurring add-on repeats a fixed number of periods, which for unlimited roaming are days.
Every unlimited roaming add-on:
- grants a high-speed data allowance for each day
- a day lasts 24 hours from activation, not a calendar day in the user's time zone
- throttles data once the day's allowance is used up, until the next day starts
- renews automatically for a fixed number of days
- is charged only once, when it's created
- starts the first time the user uses data, voice, or SMS in a country it covers, so users can buy before they travel without losing days
For example, a "5GB per day for seven days" package is an add-on with a 5GB allowance, a validity of one day, and seven total periods. Your user gets up to 35GB of high-speed data over the trip, and never more than 5GB on a single day.
These add-on fields define the behavior:
| Field | Unlimited roaming value | Description |
| ----- | ----------------------- | ----------- |
| `recurrenceType` | `recurring` | The add-on renews at the start of each period. |
| `validity.unit` | `day` | The unit of one period. |
| `validity.value` | `1` | The length of one period. |
| `validity.totalPeriods` | `2` or more | The number of periods (here: days) the package lasts. |
| `limits.throttling.thresholdBytes` | For example, `5000000000` | The high-speed data for each day, in bytes. |
| `limits.throttling.bandwidthBitsPerSecond` | For example, `1000000` | The throttled speed, in bits per second. |
| `limits.dataBytes` | For example, `16000000000` | The total data for each day, in bytes, including the throttled data. |
| `activationTrigger` | `usageStarted` | The first day starts when the user first uses the add-on. |
| `coverage` | A coverage profile | The countries where the add-on works. |
| `price` | One-time price | The price for the whole package, not per day. |
The 5GB and 1 Mbps values in this guide are examples, and the throttled speeds available vary by provider.
This guide uses one-day periods, the usual setup for unlimited roaming. A recurring add-on's period can also be a number of days or months, for example 7 days or 1 month, set through `validity.value` and `validity.unit`. The allowance, throttling, and renewal then apply per period instead of per day. Reach out to your Gigs point of contact if you need a different period length.
### Throttling
When a user uses up the day's high-speed data, the add-on keeps them connected at a throttled speed until the next day starts. Throttled data doesn't carry over to the next day.
You pick the throttled speed for each add-on, and Gigs sets it when it creates the add-on. The speeds you can choose depend on the network provider your project runs on, so agree them with your Gigs point of contact. Gigs also sets the add-on's total daily data limit so the throttled connection lasts until the next day starts.
## Before you begin
You need:
- **A subscription on a provider that supports throttling.** Ask your Gigs point of contact if you're not sure. For travel, this is usually an Evergreen Roaming subscription. To set one up, see [Implement Evergreen Roaming][implement-evergreen-roaming].
- **Your unlimited roaming add-ons.** Gigs creates and configures recurring add-ons for your project, including the daily allowance, number of days, coverage, throttled speed, and price. You'll find the add-on IDs in the [Gigs Dashboard](https://dashboard.gigs.com).
## 1. List unlimited roaming add-ons
Show your users the packages available for their destination. Filter for recurring add-ons that cover the destination country and are compatible with the plan of the user's subscription:
```bash
curl --request "GET" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/addons?recurrenceType=recurring&status=available&coverageCountry=JP&plan=${PLAN_ID}" \
--header "Accept: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}"
```
The response lists every available recurring add-on that covers Japan and is compatible with the plan, including regional add-ons:
```json
{
"object": "list",
"items": [
{
"object": "addon",
"id": "add_0SNlurA049MEWV7UnL1m1tEdJp",
"name": "Japan 5GB Daily, 7 Days",
"type": "topUp",
"recurrenceType": "recurring",
"activationTrigger": "usageStarted",
"coverage": {
"object": "coverage",
"id": "cp_japan",
"countries": ["JP"],
"name": "Japan"
},
"validity": {
"unit": "day",
"value": 1,
"totalPeriods": 7
},
"allowances": {
"dataBytes": 5000000000,
"voiceSeconds": 0,
"smsMessages": 0
},
"limits": {
"dataBytes": 16000000000,
"throttling": {
"thresholdBytes": 5000000000,
"bandwidthBitsPerSecond": 1000000
}
},
"price": {
"amount": 2999,
"currency": "USD"
}
}
],
"moreItemsAfter": null,
"moreItemsBefore": null
}
```
Use these fields to label each package in your UI, in line with [our recommendations](#on-unlimited-terminology):
| What to show | Where to find it |
| ------------ | ---------------- |
| High-speed data per day | `limits.throttling.thresholdBytes` |
| Number of days | `validity.totalPeriods` |
| Throttled speed | `limits.throttling.bandwidthBitsPerSecond`, in bits per second. For example, `1000000` is 1 Mbps. |
| Destination or region | `coverage.name`. This is a technical label in English (for example, "Europe without France"), so use it only as a key for your own translations. |
| Price for the whole package | `price.amount` in the smallest currency unit, and `price.currency` |
If the list is empty, reach out to your Gigs point of contact to check that recurring add-ons are enabled for your project and that your add-ons are `available`.
## 2. Attach the add-on to the subscription
When the user picks a package, create a subscription add-on:
```bash
curl --request "POST" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptionAddons" \
--header "Accept: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
"addon": "add_0SNlurA049MEWV7UnL1m1tEdJp",
"subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
}'
```
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `addon` | string | Required | The ID of the unlimited roaming add-on. |
| `subscription` | string | Required | The ID of the user's subscription. |
The response returns the new subscription add-on. Its status is `initiated` if billing is enabled for your project, otherwise `pending`. `currentPeriod` stays `null` until the add-on activates.
If the request fails, check that the add-on is `available` and compatible with the subscription's plan.
If billing is enabled for your project, creating the subscription add-on generates one invoice for the whole package, and the add-on can't activate until that invoice is paid. Collect payment and mark the invoice as paid if necessary, as described in [Billing Users][billing-users]. Once the invoice is paid, the subscription add-on moves to `pending`. Each renewal refreshes the daily allowance but doesn't generate another invoice. Reach out to your Gigs point of contact for questions.
## 3. Show daily progress
While the subscription add-on is `pending`, the package hasn't started yet. When the user first uses it in a covered country, it becomes `active`, `activatedAt` is set, and day one begins.
The add-on renews on its own schedule. Each day lasts 24 hours from activation, not a calendar day in the user's time zone. At the start of each day:
- the full daily allowance is available at high speed again
- unused high-speed data from the previous day doesn't carry over
- `currentPeriod.number` moves to the next day
Using up a day's allowance doesn't end the add-on. It stays `active` for the whole duration.
To show which day the user is on, retrieve the subscription add-on and compare `currentPeriod.number` with the add-on's `validity.totalPeriods`, for example "Day 3 of 7":
```bash
curl --request "GET" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptionAddons/${SUBSCRIPTION_ADDON_ID}" \
--header "Accept: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}"
```
To show how much high-speed data is left today, [list the usage balances][usage-balances-api] for the subscription add-on. Each day has two balances, one for the high-speed data and one for the throttled data, so use the ones where the current time falls between `usableFrom` and `usableUntil`. The high-speed balance is the one whose `limit` equals the add-on's `limits.throttling.thresholdBytes`, and its `remaining` field shows the high-speed data left today. The throttled balance's `limit` is `limits.dataBytes` minus `limits.throttling.thresholdBytes`. The balances for each day can differ by provider. If you don't see two balances for the current day, ask your Gigs point of contact.
```bash
curl --request "GET" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/usageBalances?subscription=${SUBSCRIPTION_ID}&subscriptionAddon=${SUBSCRIPTION_ADDON_ID}" \
--header "Accept: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}"
```
To notify your user when today's high-speed data runs out, subscribe to `com.gigs.usageBalance.thresholdReached`. For the add-on's high-speed data balance in the current day, `usedPercent` of 100 means the daily high-speed allowance is used up. The user stays connected at the configured throttled speed until the next day starts. The `throttled` usage notification isn't sent when an add-on's daily allowance runs out, so use this event instead. See [Usage Events and Notifications][usage-events] for threshold behavior.
## 4. Handle the end of the package
Shortly after the package starts, `endedAt` is set to when its last day ends, so you can show your user when the package ends. The `com.gigs.subscriptionAddon.activated` event is sent before that, so its `endedAt` is `null`. Retrieve the subscription add-on to read the end date.
After the last day, the subscription add-on moves to `ended` and `endedAt` changes to the time it actually ended. The subscription falls back to its next active allowance. On an Evergreen Roaming subscription, the base plan has no allowance, so the user has no data until they buy another package. This is a good moment to offer one.
To know when a package ends, subscribe to [`com.gigs.subscriptionAddon.ended`][subscription-addon-ended]. It fires after the last day and when you end a package early, but not when a day's high-speed data runs out.
To end a package early, delete the subscription add-on. This takes effect immediately and cancels all remaining days, so confirm with the user first:
```bash
curl --request "DELETE" \
--url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptionAddons/${SUBSCRIPTION_ADDON_ID}" \
--header "Accept: application/json" \
--header "Authorization: Bearer ${GIGS_TOKEN}"
```
## What your users experience
| Moment | What happens | What to tell your user |
| ------ | ------------ | ---------------------- |
| Purchase | The add-on is `pending` until first use. | "Your package starts when you first use data in Japan." |
| First use | The add-on is `active` and day one starts. | "Day 1 of 7: 5GB of high-speed data today." |
| Daily allowance used up | Data continues at the throttled speed until the next day. | "You've used today's high-speed data. You're still connected at 1 Mbps, and full speed returns in 6 hours." |
| New day | The full daily allowance is available at high speed. | "Day 2 of 7: your high-speed data is back." |
| Last day ends | The add-on is `ended`. | "Your package has ended. Buy another one to stay connected." |
## On "unlimited" terminology
Describe each package by what your users get, starting with the high-speed data per day, for example "5GB high-speed data daily, then data at 1 Mbps."
If you use the word "unlimited", use it as a secondary description, never for the high-speed data itself. Place the daily allowance and the throttled speed next to every use of the word, not behind a tap, tooltip, or link.
Before your user pays, show these details on the purchase screen:
- the amount of high-speed data per day
- the throttled speed after that
- the number of days in the package
- that the allowance resets every 24 hours
- that the package starts on first use
Requirements differ by market, and in some markets you may not be able to describe these packages as unlimited at all. You're responsible for how you describe and market packages to your users, and we recommend seeking legal counsel in advance.
Before launch, please share your package names and purchase screen copy with Gigs for review.
## Limitations
- **Provider:** Unlimited roaming needs a network provider that supports throttling. Ask your Gigs point of contact.
- **Fixed length:** A package lasts the number of days set in `validity.totalPeriods`, with a minimum of two. Packages that renew indefinitely aren't supported. For a single day, use a one-time add-on.
- **No overall cap:** You can't cap total data across the whole package. The maximum high-speed data is the daily allowance multiplied by the number of days.
- **Billing:** Each package generates one invoice. Renewals don't generate invoices.
- **Ending early:** Ending a package cancels all remaining days immediately.
- **Configuration:** Gigs creates and configures recurring add-ons. The throttled speeds you can choose depend on your provider.
## Related guides
- [Add-ons][add-ons]
- [Recurring add-ons][recurring-add-ons]
- [Billing Users][billing-users]
[add-ons]: /docs/core/add-ons
[recurring-add-ons]: /docs/core/recurring-add-ons
[billing-users]: /docs/billing/billing-users
[implement-evergreen-roaming]: /docs/connect/implement-evergreen-roaming
[usage-balances-api]: /api/latest/core/usage-balances
[usage-events]: /docs/core/usage/usage-events
[subscription-addon-ended]: /api/latest/events/schemas/com.gigs.subscriptionAddon.ended