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

The 5GB and 1 Mbps values in this guide are examples, and the throttled speeds available vary by provider.

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

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:

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:

{
  "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:

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:

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"
  }'

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.

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

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

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

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

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
• Recurring add-ons
• Billing Users