Sign inGet Started
Mulai sekarang
Panduan
Referensi API
SDK
CLI
Basis Pengetahuan
Changelog

Release an eSIM

DELETE
/v1/esim/sims/{esim_id}
bird esim release <esim-id> --yes
Respons202
{
  "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"
}

Permanently releases an eSIM. This is irreversible: the eSIM can never be installed or used again, any remaining package data balance is forfeited, and release never credits anything back. Use release when responding to fraud or closing out a trip; to pause service temporarily, use Suspend an eSIM instead.

Release completes asynchronously: the 202 response returns the eSIM in releasing, and the esim.released webhook event confirms completion. An eSIM with an order still in flight cannot be released: wait for the order to reach a terminal status first. When unexpired balance remains, the request fails with a conflict unless acknowledge_balance_forfeit=true.

Parameter

esim_idstring

eSIM ID.

Parameter Kueri

acknowledge_balance_forfeitboolean

Confirms you accept that remaining package balances are forfeited. Omitted or false while unexpired balance remains, the request fails with a conflict error.

Payload Respons

subscriber_id
nullable string
wajib

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

id
string
wajib
status
string
wajib
mode
string
wajib
iccid
nullable string
wajib

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

phone_number
nullable string
wajib

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
Tampilkan atribut turunan
order_id
string
wajib

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
wajib
Tampilkan atribut turunan
packages
array of object
wajib

Current data packages, one per purchase.

Tampilkan atribut turunan
packages.id
string
wajib
packages.order_id
string
wajib

The order that purchased this package.

packages.offer_id
string
wajib

Offer this package was purchased from.

packages.zone_id
string
wajib

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
wajib

Coverage zone name, from the offer.

packages.countries
array of string
wajib

Countries the package's zone covers, captured at purchase time so the package is meaningful without fetching the offer.

packages.status
string
wajib
packages.speed
string
wajib

Speed class, from the offer.

packages.balance
object
wajib
Tampilkan atribut turunan
packages.balance.total_bytes
integer
wajib

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

packages.balance.used_bytes
nullable integer
wajib

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

packages.balance.remaining_bytes
nullable integer
wajib

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

packages.balance.used_percent
nullable number
wajib

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

packages.balance.as_of
string
wajib

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
wajib

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
wajib

What your workspace was billed for this package.

Tampilkan atribut turunan
packages.created_at
string
wajib
zone_balances
array of object
wajib

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

Tampilkan atribut turunan
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.

Tampilkan atribut turunan
package_limit
integer
wajib

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
wajib

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
wajib

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.

Tampilkan atribut turunan
tags
array of object

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

Tampilkan atribut turunan
metadata
object

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

created_at
string
wajib
updated_at
string
wajib

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.

Dapatkan ringkasan implementasi