Sign inGet Started
Rozpocznij
Przewodniki
Referencja API
SDK
CLI
Baza wiedzy
Changelog

Update an eSIM

PATCH
/v1/esim/sims/{esim_id}
bird esim update <esim-id> --tags category=welcome
Odpowiedź200
{
  "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.

Parametry

esim_idstring

eSIM ID.

Treść żądania

display_name
nullable string

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

tags
array of object

Replaces the eSIM's tags.

Pokaż parametry podrzędne
metadata
object

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

Treść odpowiedzi

subscriber_id
nullable string
wymagane

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

id
string
wymagane
status
string
wymagane
mode
string
wymagane
iccid
nullable string
wymagane

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

phone_number
nullable string
wymagane

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
Pokaż atrybuty podrzędne
order_id
string
wymagane

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
wymagane
Pokaż atrybuty podrzędne
packages
array of object
wymagane

Current data packages, one per purchase.

Pokaż atrybuty podrzędne
zone_balances
array of object
wymagane

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

Pokaż atrybuty podrzędne
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.

Pokaż atrybuty podrzędne
available_actions.action
string
wymagane
available_actions.operation
string
wymagane

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

available_actions.available
boolean
wymagane

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
wymagane

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
wymagane

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
wymagane

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
wymagane

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.

Pokaż atrybuty podrzędne
tags
array of object

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

Pokaż atrybuty podrzędne
metadata
object

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

created_at
string
wymagane
updated_at
string
wymagane

Powiązane zasoby

Przejdź do dokumentacji, przewodników i przykładów dotyczących tego tematu.

Uzyskaj brief wdrożeniowy