Sign inGet Started

Update an eSIM

PATCH
/v1/esim/sims/{esim_id}
bird esim update <esim-id> --tags category=welcome
Réponse200
{
  "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"
}

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

Paramètres

esim_idstring

eSIM ID.

Corps de la requête

display_name
nullable string

Free-text label for your own reference. Null clears it.

tags
array of object

Replaces the eSIM's tags.

Afficher les paramètres enfants
metadata
object

Replaces the eSIM's metadata. Maximum 2 KB serialized.

Contenu de la réponse

subscriber_id
nullable string
obligatoire

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

id
string
obligatoire
status
string
obligatoire

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, when known, to stay within the guaranteed activation window.
  • 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
obligatoire

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
obligatoire

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

phone_number
nullable string
obligatoire

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.

Afficher les attributs enfants
order_id
string
obligatoire

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
obligatoire

Device-side installation state of the eSIM profile.

Afficher les attributs enfants
packages
array of object
obligatoire

Current data packages, one per purchase.

Afficher les attributs enfants
zone_balances
array of object
obligatoire

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

Afficher les attributs enfants
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.

Afficher les attributs enfants
available_actions.action
string
obligatoire

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.

Possible values (may grow over time): suspend, resume, release, install, top_up, assign

available_actions.operation
string
obligatoire

Operation to call for this action. Consult that operation’s reference for its request and response.

available_actions.available
boolean
obligatoire

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
obligatoire

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

Possible values (may grow over time): permission_denied, network_unsupported, network_unconfirmed, esim_state, operation_in_progress, package_limit_reached, identification_required

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
obligatoire

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
obligatoire

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
obligatoire

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

Guaranteed deadline for first network use, derived from the initial purchase's accepted activation window. The activation window is separate from package validity. Null when the window is unconfirmed, first use has been reported, or the eSIM has been released. Top-ups do not restart this deadline.

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.

Afficher les attributs enfants
tags
array of object

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

Afficher les attributs enfants
metadata
object

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

created_at
string
obligatoire
updated_at
string
obligatoire

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.