---
title: "Resume an eSIM"
canonical: "https://bird.com/docs/api/reference/resume-esim"
---

# Resume an eSIM

`POST /v1/esim/sims/{esim_id}/resume`

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.

## Code samples

**CLI**

```sh
bird esim resume <esim-id>
```

Examples: [CLI](/docs/api/reference/resume-esim.cli.md) · [MCP](/docs/api/reference/resume-esim.mcp.md) · [cURL](/docs/api/reference/resume-esim.curl.md)

## Example response `202`

```json
{
  "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"
}
```

## Path parameters

- `esim_id` (string): eSIM ID.

## Response body

- `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)
- `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)
- `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.
- `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)
- `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 the balance was last established. Before consumption is reported, this is the package delivery time. Check whether the consumption fields are null before treating this timestamp as a usage update.
- `packages.balance.observed_at` (nullable string, required): Measurement time supplied by the mobile network. Null when no measurement or measurement time is available. Use `as_of` for the balance update time.
- `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.
- `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.
- `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): Reported data used in this zone, in bytes. Null if any contributing package lacks a usage report. Read individual package balances for available measurements.
- `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): Oldest network measurement time among the contributing packages. Null if any package lacks a report or a measurement time. Use `as_of` for the balance update time.
- `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.
- `available_actions.action` (string, required)
- `available_actions.operation` (string, required): Operation to call for this action. Consult that operation’s reference for its request and response.
- `available_actions.available` (boolean, required): Whether the action is available given your permissions and the current eSIM state. The action checks these again when submitted; a later request can be refused if conditions change.
- `available_actions.reason` (nullable string, required): Why the action is unavailable. Null while `available` is true.
- `available_actions.requires` (array of string): Additional parameters required by the current state, such as `acknowledge_balance_forfeit` when releasing an eSIM with remaining data. Absent when no additional parameters apply or when permissions, network support, or profile state prevent the action.
- `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.
- `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.
- `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.
- `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

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)