Sign inGet Started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Resume an eSIM

POST
/v1/esim/sims/{esim_id}/resume
bird esim resume <esim-id>
Response202
{
  "subscriber_id": "esub_01krdgeqcxet5s7t44vh8rt9mg",
  "id": "esm_01krdgeqcxet5s7t44vh8rt9mg",
  "status": "provisioning",
  "mode": "live",
  "iccid": "8944500212345678912",
  "phone_number": "+31612345678",
  "capabilities": {
    "data": "yes",
    "sms_inbound": "yes",
    "sms_outbound": "yes",
    "voice_inbound": "yes",
    "voice_outbound": "yes"
  },
  "order_id": "eor_01krdgeqcxet5s7t44vh8rt9mg",
  "display_name": "Amsterdam trip, order 8812",
  "installation": {
    "state": "pending"
  },
  "packages": [
    {
      "id": "epk_01krdgeqcxet5s7t44vh8rt9mg",
      "order_id": "eor_01krdgeqcxet5s7t44vh8rt9mg",
      "offer_id": "eof_01krdgeqcxet5s7t44vh8rt9mg",
      "zone_id": "ezn_01krdgeqcxet5s7t44vh8rt9mg",
      "zone_name": "Europe",
      "countries": [
        "US"
      ],
      "status": "provisioning",
      "speed": "full",
      "price": {
        "amount": "0.00995",
        "currency_code": "USD"
      }
    }
  ],
  "zone_balances": [
    {
      "zone_id": "ezn_01krdgeqcxet5s7t44vh8rt9mg"
    }
  ],
  "available_actions": [
    {
      "action": "suspend",
      "operation": "suspendEsim",
      "reason": "permission_denied",
      "requires": [
        "acknowledge_balance_forfeit"
      ]
    }
  ],
  "package_limit": 3,
  "usage_available": true,
  "balance_reporting": "available",
  "last_attachment": {
    "country_code": "US"
  },
  "tags": [
    {
      "name": "category",
      "value": "welcome"
    }
  ],
  "created_at": "2026-05-20T09:14:52Z",
  "updated_at": "2026-05-25T16:42:01Z"
}

Resumes a suspended eSIM so it can use data again. Completes asynchronously; the esim.resumed webhook event confirms it. Resuming an eSIM that is not suspended returns a conflict.

Parameters

esim_idstring

eSIM ID.

Response Payload

subscriber_id
nullable string
required

The assigned service user, or null when the eSIM has no person assignment.

id
string
required
status
string
required

Lifecycle state of an eSIM. A pending state always settles: to its target on success, or back to the prior status when the network definitively rejects the change, reported by the esim.operation_failed event.

  • provisioning: the initial data package is being applied; install credentials may already be available.
  • ready: installable and usable, waiting for first network use; allows top-up orders and release. Activate before ready_until or the eSIM expires.
  • activating: an activation is being applied.
  • active: in service; the service period ends at active_until. Allows top-up orders, suspend, resync, and release.
  • suspending: a suspension was requested and is being applied.
  • suspended: data service is paused; allows resume and release.
  • resuming: a resume was requested and is being applied.
  • releasing: a permanent release is in progress.
  • released: permanently released; terminal.
  • expired: dormant. No data package has been live (each one depleted, expired, removed, or failed) for the expiry window. Not terminal: a completed top-up returns the eSIM to active, and release remains available. Balances and the installed profile are untouched.
  • failed: provisioning failed; any charge on the owning order is credited back automatically, reported by that order. Terminal.

Possible values: provisioning, ready, activating, active, suspending, suspended, resuming, releasing, released, expired, failed

mode
string
required

Whether a purchase or eSIM is live or simulated. The mode is fixed when the order is created; the resulting eSIM retains it.

  • live: purchases service for use on a device and charges the wallet.
  • test: simulates a purchase without a charge or usable mobile service.

List responses can include both modes. Filter by mode when separating test activity from live purchases.

Possible values: live, test

iccid
nullable string
required

ICCID of the eSIM profile. Null while no profile is allocated yet, for example when provisioning failed before allocation.

phone_number
nullable string
required

Phone number attached to this eSIM, in E.164 format, as the supplier reports it. Null while none is on record: a data-only plan comes with no number, and a plan that includes one reports it after provisioning.

capabilities
object

Supported services for the eSIM. These values describe capabilities; package balances and current eSIM status determine whether service can be used now. Optional phone service can remain unknown until a number is assigned. Data packages do not establish call or SMS allowances.

Show child attributes
order_id
string
required

The order that created this eSIM.

display_name
nullable string

Free-text label for your own reference, for example a traveler or order reference.

installation
object
required

Device-side installation state of the eSIM profile.

Show child attributes
packages
array of object
required

Current data packages, one per purchase.

Show child attributes
packages.id
string
required
packages.order_id
string
required

The order that purchased this package.

packages.offer_id
string
required

Offer this package was purchased from.

packages.zone_id
string
required

Coverage zone the package draws on. The name and countries below are captured at purchase time; the zone resource carries the live footprint.

packages.zone_name
string
required

Coverage zone name, from the offer.

packages.countries
array of string
required

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

packages.status
string
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.

Possible values: provisioning, pending_first_use, active, depleted, expired, removing, removed, failed

packages.speed
string
required

Speed class, from the offer.

Possible values: full, reduced

packages.balance
object
required

Package allowance and reported consumption. total_bytes is the purchased allowance. used_bytes, remaining_bytes, and used_percent are null until usage is reported. Reports can lag device usage; use as_of to show when the balance was updated.

Show child attributes
packages.activated_at
nullable string

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

packages.expires_at
nullable string

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.

packages.price
object
required

What your workspace was billed for this package.

Show child attributes
packages.price.amount
string
required

Decimal amount as a string, in major currency units.

packages.price.currency_code
string
required

ISO 4217 currency code.

packages.created_at
string
required
zone_balances
array of object
required

Remaining data per coverage zone, combined across the zone's packages. Derived; the packages are the source of truth.

Show child attributes
available_actions
array of object

Actions currently available to you on this eSIM, with reasons for unavailable actions. Returned by the individual eSIM read. Use this to display controls and explain restrictions. Each action rechecks permissions and state when submitted, so availability is not a guarantee of success.

Show child attributes
package_limit
integer
required

Maximum number of concurrent data packages this eSIM can hold, counted across all zones; several packages may share one zone. Enforced when packages are added.

usage_available
boolean
required

Whether daily usage history is supported for this eSIM. The daily usage endpoint is currently unavailable; read package balances for reported consumption.

balance_reporting
string
required

Whether ongoing package consumption reporting is available. Separate from daily usage history. Null package consumption values mean no measurement is available.

Possible values: available, unavailable

ready_until
nullable string

Activate (first network use) before this moment or the eSIM expires. Null once activated.

activated_at
nullable string

When the eSIM first used a mobile network. Null until then.

active_until
nullable string

When the eSIM's service period ends. The period starts at activation and data packages cannot outlive it. Null until activated.

last_attachment
nullable object

Most recent network attachment, or null before first attach.

Show child attributes
tags
array of object

Tags for routing, filtering, and stats grouping, echoed on webhook events for the eSIM.

Show child attributes
metadata
object

Your own key-value data, echoed on webhook events for the eSIM. Maximum 2 KB serialized.

created_at
string
required
updated_at
string
required

Related resources

Continue with the documentation, guides and examples for this topic.

Get an implementation brief