Sign inGet Started
Inizia ora
Guide
Riferimento API
SDK
CLI
Knowledge Base
Changelog

Release an eSIM

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

Parametri

esim_idstring

eSIM ID.

Parametri di query

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 di risposta

subscriber_id
nullable string
obbligatorio

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

id
string
obbligatorio
status
string
obbligatorio
mode
string
obbligatorio
iccid
nullable string
obbligatorio

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

phone_number
nullable string
obbligatorio

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
Mostra attributi secondari
order_id
string
obbligatorio

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
obbligatorio
Mostra attributi secondari
installation.state
string
obbligatorio

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
obbligatorio

Current data packages, one per purchase.

Mostra attributi secondari
zone_balances
array of object
obbligatorio

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

Mostra attributi secondari
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.

Mostra attributi secondari
package_limit
integer
obbligatorio

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
obbligatorio

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
obbligatorio

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.

Mostra attributi secondari
tags
array of object

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

Mostra attributi secondari
metadata
object

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

created_at
string
obbligatorio
updated_at
string
obbligatorio

Risorse correlate

Continua con la documentazione, le guide e gli esempi per questo argomento.

Ottieni un brief di implementazione