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
mode
string
required
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
Show child attributes
capabilities.data
string
required

Whether a service is supported. yes confirms support, no confirms it is not supported, and unknown means support has not been established.

Possible values: yes, no, unknown

capabilities.sms_inbound
string
required

Whether a service is supported. yes confirms support, no confirms it is not supported, and unknown means support has not been established.

Possible values: yes, no, unknown

capabilities.sms_outbound
string
required

Whether a service is supported. yes confirms support, no confirms it is not supported, and unknown means support has not been established.

Possible values: yes, no, unknown

capabilities.voice_inbound
string
required

Whether a service is supported. yes confirms support, no confirms it is not supported, and unknown means support has not been established.

Possible values: yes, no, unknown

capabilities.voice_outbound
string
required

Whether a service is supported. yes confirms support, no confirms it is not supported, and unknown means support has not been established.

Possible values: yes, no, unknown

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
Show child attributes
installation.state
string
required

pending: not yet downloaded by a device; downloaded: downloaded but not installed; installed: installed on the device; removed: deleted from the device; whether the profile can be installed again depends on the carrier profile, so treat removal as final; error: download or installation failed, see error_reason. Open enum: installation state is reported by the device, so additional states may be added over time. Treat an unrecognized value as a future state, not an error.

Possible values (may grow over time): pending, downloaded, installed, removed, error

installation.updated_at
nullable string

When the installation state last changed. Null before the first device interaction.

installation.error_reason
nullable string

Human-readable reason installation failed, for example an ineligible device or an exhausted download limit. Null unless state is error.

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
packages.speed
string
required

Speed class, from the offer.

packages.balance
object
required
Show child attributes
packages.balance.total_bytes
integer
required

Total data in bytes, as purchased. Known from the order, so never null.

packages.balance.used_bytes
nullable integer
required

Data used in bytes, or null while no network has reported on this package.

packages.balance.remaining_bytes
nullable integer
required

Data remaining in bytes, or null while no network has reported on this package.

packages.balance.used_percent
nullable number
required

Share of the total data already used, as a percentage. Null while no network has reported on this package.

packages.balance.as_of
string
required

When these figures were last established. This is the field to show as freshness, and it is always present: on a package nothing has reported on it is the delivery, which is why it cannot tell you whether anything was measured. Once something has, it is the moment Bird read the balance, or the time an end-of-period notification stated, falling back to when Bird received that notification.

packages.balance.observed_at
nullable string
required

The instant the serving network itself stated for this reading. Usually null, and null in two different ways: no network has reported on the package yet, or one reported without naming a time. Today every balance read falls in the second case, because the carrier interfaces Bird reads return a remainder and no measurement time, and end-of-period notifications often name none either. Bird never substitutes its own clock here - a timestamp we invented would read as a measurement we did not take - so treat a null as "no network time available" and fall back to as_of, which says when Bird looked.

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
zone_balances.zone_id
string
required
zone_balances.total_bytes
integer
required

Total purchased data for the zone, in bytes. Known from the orders, so never null.

zone_balances.used_bytes
nullable integer
required

Data used, in bytes. Null unless every package behind this figure has been reported on: a sum is only as measured as its least measured part, and one unreported package makes it part measurement and part purchased allowance, which is not consumption. The packages carry their own figures, so the measured ones stay readable there.

zone_balances.remaining_bytes
nullable integer
required

Data remaining, in bytes. Null under the same condition as used_bytes.

zone_balances.as_of
string
required

Freshness of this combined figure - the oldest balance read among the zone's contributing packages. Each package's own balance.as_of can be newer.

zone_balances.observed_at
nullable string
required

The oldest network-stated instant behind this combined figure. Null whenever any contributing package is unreported, and also, more often, because the carrier interfaces Bird reads state no instant at all. Use as_of for freshness.

available_actions
array of object

What this eSIM permits you to do right now, with a reason for each action it does not. Every action we report on is listed, whether or not it is available, so a false with a reason is the answer and a missing entry never is. The eSIM read always sends this. It is absent only where this schema is reused to list eSIMs, since the answer is per caller and a list does not carry it. This is advice for deciding what to offer and what to explain, never authorization: it is evaluated when the eSIM is read, and each operation re-checks all of it when called. Do not cache it as a grant.

Show child attributes
available_actions.action
string
required
available_actions.operation
string
required

The operationId that performs the action. The operation's own reference page says how to call it; this says only which one.

available_actions.available
boolean
required

Whether the action would be accepted as this eSIM stands. Advice, not permission to act: it is evaluated when the eSIM is read, and the operation checks everything here again when you call it. A true that has gone stale is refused at that point, so treat it as a reason to offer the action rather than as a guarantee it will succeed.

available_actions.reason
nullable string
required

Why the action is unavailable. Null while available is true.

available_actions.requires
array of string

Parameters this eSIM's current state makes mandatory, which the operation's own schema can only describe as optional. Releasing an eSIM that still holds paid data requires acknowledge_balance_forfeit, for example. Absent when the current state makes nothing extra mandatory, and absent on an action refused for your permissions, the serving network, or a state that forbids it, since there is no call to add a parameter to. A refusal you can wait out still carries it.

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 records exist for this eSIM. False when the serving network keeps no queryable usage history: balances and packages still work, and the usage read returns an empty list rather than zeros.

balance_reporting
string
required

Whether this eSIM's data consumption is reported at all, which is what tells an absent consumption figure apart from one that will never exist. Separate from usage_available: that answers whether the day-by-country usage read has records, this answers whether the package balances carry consumption.

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
last_attachment.country_code
string
required

Country of the network.

last_attachment.country_name
nullable string

English name of the country, or null when not known.

last_attachment.network_name
nullable string

Name of the mobile network, or null when not known.

last_attachment.attached_at
string
required

When the device attached.

tags
array of object

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

Show child attributes
tags.name
string
required

Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.

tags.value
string
required

Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.

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