Data plans

A plan is the combination of an allowance, a region, and a validity window. Ordering a plan onto an eSIM creates a package: the live instance with its own usage counters and expiry.

{
  "planReference": "C123456XYZDUSR",
  "name": "5GB - 30 Days - US",
  "type": "data",
  "capacityMb": 5120,
  "speedKbps": 100000,
  "throttleCapacityMb": 1024,
  "throttleSpeedKbps": 512,
  "validityMinutes": 43200,
  "countryCode": "US",
  "recurring": false
}

type is data, sms or voice; SMS and voice plans carry smsCount or voiceSeconds in place of the data fields.

The planReference reads as C/S for client-specific or shared, then a client segment and three random characters, then a type letter (D data, M SMS, V voice), the country, and a final R/N for recurring or one-off. Useful when you're reading a log, but don't build on it: references are opaque tokens whose format can change, so store them verbatim and take your facts from the response body.

Browsing the catalogue

firsty catalog packages --country US

GET /catalog/regions lists where plans exist, and GET /catalog/coverage/{regionCode} shows the actual networks and technologies behind a region. Country plans are cheaper per gigabyte; global plans are simpler to support. Most integrations offer both and let the user choose at checkout.

Allowances and throttling

What happens at the cap depends on the plan. Plans with throttleCapacityMb drop to throttleSpeedKbps after the main allowance. Data keeps flowing, slowly. Plans without throttling stop passing data at the cap.

Which webhook tells you the allowance is gone depends on the plan too. A recurring package emits package.throttled and waits for its next renewal; a one-off package emits package.exhausted. Either is the moment to offer a top-up.

Recurring plans (recurring: true) renew themselves every renewalPeriodMinutes and emit package.renewed.

Top-ups

A top-up is just another package on the same eSIM: no reissuing, no reinstall, same profile on the device:

firsty package order C123456XYZDUSR

GET .../packages lists what's currently on the eSIM, and GET .../usage aggregates consumption across all of them.