---
title: "Update an eSIM"
method: PATCH
path: "/v1/esim/sims/{esim_id}"
tags: ["esims"]
---

# Update an eSIM

`PATCH /v1/esim/sims/{esim_id}`

## Request

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

Updates the eSIM's display name, tags, or metadata. Lifecycle and connectivity are managed through the dedicated endpoints.

## Headers

- `Idempotency-Key` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Request body

- EsimUpdate: Fields that can be updated on an eSIM.
  - `display_name` string, nullable: Free-text label for your own reference. Null clears it.
  - `tags` Tag[]: Replaces the eSIM's tags.
    - `name` string, required: Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
    - `value` string, required: Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
  - `metadata` object: Replaces the eSIM's metadata. Maximum 2 KB serialized.

## Response `200`

The updated eSIM.

- Esim
  - `subscriber_id` string, required
  - `id` string, required
  - `status` 'provisioning' | 'ready' | 'activating' | 'active' | 'suspending' | 'suspended' | 'resuming' | 'releasing' | 'released' | 'expired' | 'failed', 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.
  - `mode` 'live' | 'test', 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.
  - `iccid` string, nullable, required: ICCID of the eSIM profile. Null while no profile is allocated yet, for example when provisioning failed before allocation.
  - `phone_number` string, nullable, 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` EsimServiceCapabilities: 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.
    - `data` 'yes' | 'no' | 'unknown', required: Whether a service is supported. `yes` confirms support, `no` confirms it is not supported, and `unknown` means support has not been established.
    - `sms_inbound` 'yes' | 'no' | 'unknown', required: Whether a service is supported. `yes` confirms support, `no` confirms it is not supported, and `unknown` means support has not been established.
    - `sms_outbound` 'yes' | 'no' | 'unknown', required: Whether a service is supported. `yes` confirms support, `no` confirms it is not supported, and `unknown` means support has not been established.
    - `voice_inbound` 'yes' | 'no' | 'unknown', required: Whether a service is supported. `yes` confirms support, `no` confirms it is not supported, and `unknown` means support has not been established.
    - `voice_outbound` 'yes' | 'no' | 'unknown', required: Whether a service is supported. `yes` confirms support, `no` confirms it is not supported, and `unknown` means support has not been established.
  - `order_id` string, required
  - `display_name` string, nullable: Free-text label for your own reference, for example a traveler or order reference.
  - `installation` EsimInstallation, required: Device-side installation state of the eSIM profile.
    - `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.
    - `updated_at` string, date-time, nullable: When the installation state last changed. Null before the first device interaction.
    - `error_reason` string, nullable: Human-readable reason installation failed, for example an ineligible device or an exhausted download limit. Null unless state is error.
  - `packages` EsimPackage[], required: Current data packages, one per purchase.
    - `id` string, required
    - `order_id` string, required
    - `offer_id` string, required
    - `zone_id` string, required
    - `zone_name` string, required: Coverage zone name, from the offer.
    - `countries` CountryCode[], 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.
    - `balance` EsimPackageBalance, 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.
      - `total_bytes` integer, required: Total data in bytes, as purchased. Known from the order, so never null.
      - `used_bytes` integer, nullable, required: Data used in bytes, or null while no network has reported on this package.
      - `remaining_bytes` integer, nullable, required: Data remaining in bytes, or null while no network has reported on this package.
      - `used_percent` number, nullable, required: Share of the total data already used, as a percentage. Null while no network has reported on this package.
      - `as_of` string, date-time, 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.
      - `observed_at` string, date-time, nullable, 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.
    - `activated_at` string, date-time, nullable: When the package started consuming data (first use in its zone). Null until then.
    - `expires_at` string, 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.
    - `price` Money, required
      - `amount` string, required: Decimal amount as a string, in major currency units.
      - `currency_code` string, required: ISO 4217 three-letter currency code.
    - `created_at` string, date-time, required
  - `zone_balances` EsimZoneBalance[], required: Remaining data per coverage zone, combined across the zone's packages. Derived; the packages are the source of truth.
    - `zone_id` string, required
    - `total_bytes` integer, required: Total purchased data for the zone, in bytes. Known from the orders, so never null.
    - `used_bytes` integer, nullable, 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.
    - `remaining_bytes` integer, nullable, required: Data remaining, in bytes. Null under the same condition as `used_bytes`.
    - `as_of` string, date-time, 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.
    - `observed_at` string, date-time, nullable, 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` EsimAvailableAction[]: 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.
    - `action` string, required: An operation you can attempt on an eSIM. - `suspend`: pause data service, keeping packages and their validity running. - `resume`: restore service to a suspended eSIM. - `release`: permanently retire the eSIM. - `install`: read the install credentials for a device. - `top_up`: order another data package onto this eSIM. - `assign`: assign an unassigned profile to a person, or read back the same assignment. Tolerate a value you do not recognize: we report on more actions over time.
    - `operation` string, required: Operation to call for this action. Consult that operation’s reference for its request and response.
    - `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.
    - `reason` string, required: Reason an action is unavailable. - `permission_denied`: your credentials lack the required permission. Update permissions and check availability again; another restriction may still apply. - `network_unsupported`: the serving mobile network does not support the action for this eSIM. - `network_unconfirmed`: support for the action has not been confirmed. Contact support if you need it. - `esim_state`: the profile is not in a state that permits the action. Check the eSIM status. - `operation_in_progress`: an existing order must finish before this action can proceed. - `package_limit_reached`: the eSIM has reached its concurrent package limit. A depleted package still occupies a slot until it expires or is removed. - `identification_required`: retained for compatibility; subscriber assignment no longer returns this reason. Treat an unrecognized reason as unavailable and avoid automatically retrying the action.
    - `requires` 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` 'available' | 'unavailable', required: Whether package consumption can be reported for this eSIM. - `available`: consumption reporting has not been ruled out. A null package balance means no measurement is available yet. - `unavailable`: ongoing consumption reporting is unavailable. Display the purchased `total_bytes` as allowance; do not present it as measured remaining data. This field is separate from daily usage history. Reporting availability can change as network support is confirmed.
  - `ready_until` string, date-time, nullable: Activate (first network use) before this moment or the eSIM expires. Null once activated.
  - `activated_at` string, date-time, nullable: When the eSIM first used a mobile network. Null until then.
  - `active_until` string, date-time, nullable: When the eSIM's service period ends. The period starts at activation and data packages cannot outlive it. Null until activated.
  - `last_attachment` EsimNetworkAttachment: The most recent mobile network the device attached to.
    - `country_code` string, required: ISO 3166-1 alpha-2 country code.
    - `country_name` string, nullable: English name of the country, or null when not known.
    - `network_name` string, nullable: Name of the mobile network, or null when not known.
    - `attached_at` string, date-time, required: When the device attached.
  - `tags` Tag[]: Tags for routing, filtering, and stats grouping, echoed on webhook events for the eSIM.
    - `name` string, required: Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
    - `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, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)