esims

Create a recurring eSIM subscription

Starts a recurring package on an assigned eSIM and purchases the first period. Each accepted period is funded from your organization's wallet. A changed price requires new acceptance; an unfunded renewal or confirmed delivery failure stops future renewal.

An Idempotency-Key is required. Reuse the same key and request to recover the enrollment, including after the original response is no longer retained. Reusing the key with different enrollment details returns 409. Read the subscription and its period history to check payment and package delivery separately.

post/v1/esim/subscriptions

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/esim/subscriptions
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Headers

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.

Idempotency-Keystring required

Required client-supplied deduplication key for this write. Reuse it for retries of the same intent. Successful results replay within the configured idempotency window (three hours by default); selected connected-app writes also replay uncertain-write conflicts. Use a new key only after confirming the prior result and beginning a different action.

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.

Request body

esim_idstring required
offer_idstring required
offer_revisioninteger required

The accepted offer revision.

recurrence_revisioninteger required

The accepted recurring configuration revision.

Example request

{
  "esim_id": "esm_01krdgeqcxet5s7t44vh8rt9mg",
  "offer_id": "eof_01krdgeqcxet5s7t44vh8rt9mg",
  "offer_revision": 1,
  "recurrence_revision": 1,
  "accepted_price": {
    "amount": "0.00995",
    "currency_code": "EUR"
  }
}

Response

The requested resource.

OR

Example response

{
  "id": "ers_01krdgeqcxet5s7t44vh8rt9mg",
  "esim_id": "esm_01krdgeqcxet5s7t44vh8rt9mg",
  "initial_order_id": "eor_01krdgeqcxet5s7t44vh8rt9mg",
  "subscriber_id": "esub_01krdgeqcxet5s7t44vh8rt9mg",
  "offer_id": "eof_01krdgeqcxet5s7t44vh8rt9mg",
  "latest_order_id": "eor_01krdgeqcxet5s7t44vh8rt9mg",
  "price": {
    "amount": "0.00995",
    "currency_code": "EUR"
  }
}

Changes

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