esims

Get a data package

Returns one data package with its balance, validity, speed class, and status.

get/v1/esim/sims/{esim_id}/packages/{package_id}

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/esim/sims/{esim_id}/packages/{package_id}
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Headers

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

The package.

idstring required
order_idstring required
offer_idstring required
zone_idstring required
zone_namestring required

Coverage zone name, from the offer.

countriesCountryCode[] required

Countries the package's zone covers, captured at purchase time so the package is meaningful without fetching the offer.

status'provisioning' | 'pending_first_use' | 'active' | 'depleted' | 'expired' | 'removing' | 'removed' | 'failed' required

Lifecycle state of a data package.

  • provisioning: being applied to the eSIM.
  • pending_first_use: confirmed; activates on first use in its coverage zone.
  • active: consuming data; validity is running.
  • depleted: balance fully used.
  • expired: validity ended; unused balance is gone.
  • removing: a removal was requested and is being applied. On definitive rejection the package returns to its prior status, reported by esim.operation_failed.
  • removed: taken off the eSIM at your request; remaining balance forfeited.
  • failed: could not be applied; any charge is credited back automatically through the owning order, which reports this through its failed status and the esim.order.failed event.
speed'full' | 'reduced' required

Speed class. full: data flows at full network speed until the allowance is used; reduced: speed is limited, typically after the full-speed allowance. Full-speed and reduced-speed packages cannot be combined on one eSIM.

activated_atstring date-time nullable

When the package started consuming data (first use in its zone). Null until then.

expires_atstring date-time nullable

When the package's validity ends and unused balance expires. Already capped by the eSIM's service period, so this is always the effective expiry. Null until the package activates.

created_atstring date-time required

Example response

{
  "id": "epk_01krdgeqcxet5s7t44vh8rt9mg",
  "order_id": "eor_01krdgeqcxet5s7t44vh8rt9mg",
  "offer_id": "eof_01krdgeqcxet5s7t44vh8rt9mg",
  "zone_id": "ezn_01krdgeqcxet5s7t44vh8rt9mg",
  "zone_name": "Europe",
  "countries": [
    "US"
  ],
  "price": {
    "amount": "0.00995",
    "currency_code": "EUR"
  }
}

Changes

No recorded changes to this operation across all 3 revisions of this API.