esims

Remove a data package

Removes a data package and frees capacity under the eSIM's package_limit. Remaining data is forfeited without a refund. If usable balance remains, the request returns 409 unless acknowledge_balance_forfeit=true.

A 202 response returns the package in removing. Use Get a data package to confirm removed. If the network rejects removal, the package returns to its previous status.

delete/v1/esim/sims/{esim_id}/packages/{package_id}

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/esim/sims/{esim_id}/packages/{package_id}
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Query parameters

acknowledge_balance_forfeitboolean

Confirms you accept that the package's remaining balance is forfeited. Omitted or false while 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

Removal in progress. The returned package is in removing; it reaches removed once complete, confirmed by the esim.package.removed event.

idstring required
order_idstring required
offer_idstring required
zone_idstring required
zone_namestring required

Coverage zone name, from the offer.

countriesCountryCode[] required

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

status'provisioning' | 'pending_first_use' | 'active' | 'depleted' | 'expired' | 'removing' | 'removed' | 'failed' required

Lifecycle state of a data package.

  • provisioning: being applied to the eSIM.
  • pending_first_use: confirmed; activates on first use in its coverage zone.
  • active: consuming data; validity is running.
  • depleted: balance fully used.
  • expired: validity ended; unused balance is gone.
  • removing: a removal was requested and is being applied. On definitive rejection the package returns to its prior status, reported by esim.operation_failed.
  • removed: taken off the eSIM at your request; remaining balance forfeited.
  • failed: could not be applied; any charge is credited back automatically through the owning order, which reports this through its failed status and the esim.order.failed event.
speed'full' | 'reduced' required

Speed class. full: data flows at full network speed until the allowance is used; reduced: speed is limited, typically after the full-speed allowance. Full-speed and reduced-speed packages cannot be combined on one eSIM.

activated_atstring date-time nullable

When the package started consuming data (first use in its zone). Null until then.

expires_atstring date-time nullable

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.

created_atstring date-time required

Example response

{
  "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"
  }
}

Changes

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