esims

Release an eSIM

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.

delete/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

Query parameters

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.

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

Release in progress. The eSIM is in releasing and transitions to released when complete.

subscriber_idstring required

idstring 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.

iccidstring nullable required

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

phone_numberstring 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.

order_idstring required

display_namestring nullable

Free-text label for your own reference, for example a traveler or order reference.

package_limitinteger 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_availableboolean 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_untilstring date-time nullable

Activate (first network use) before this moment or the eSIM expires. Null once activated.

activated_atstring date-time nullable

When the eSIM first used a mobile network. Null until then.

active_untilstring date-time nullable

When the eSIM's service period ends. The period starts at activation and data packages cannot outlive it. Null until activated.

metadataobject

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

created_atstring date-time required

updated_atstring date-time required

Example response

{
  "subscriber_id": "esub_01krdgeqcxet5s7t44vh8rt9mg",
  "id": "esm_01krdgeqcxet5s7t44vh8rt9mg",
  "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",
  "packages": [
    {
      "id": "epk_01krdgeqcxet5s7t44vh8rt9mg",
      "order_id": "eor_01krdgeqcxet5s7t44vh8rt9mg",
      "offer_id": "eof_01krdgeqcxet5s7t44vh8rt9mg",
      "zone_id": "ezn_01krdgeqcxet5s7t44vh8rt9mg",
      "zone_name": "Europe",
      "countries": [
        "US"
      ],
      "price": {
        "amount": "0.00995",
        "currency_code": "EUR"
      }
    }
  ],
  "zone_balances": [
    {
      "zone_id": "ezn_01krdgeqcxet5s7t44vh8rt9mg"
    }
  ],
  "available_actions": [
    {
      "operation": "suspendEsim",
      "requires": [
        "acknowledge_balance_forfeit"
      ]
    }
  ],
  "package_limit": 3,
  "usage_available": true,
  "last_attachment": {
    "country_code": "US"
  },
  "tags": [
    {
      "name": "category",
      "value": "welcome"
    }
  ],
  "created_at": "2026-05-20T09:14:52Z",
  "updated_at": "2026-05-25T16:42:01Z"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.