eSIM

Purchase a topup for an existing eSIM

Convenience endpoint that forwards to POST /esims with parent_order_id set to this eSIM's id. The path value takes precedence over any parent_order_id in the request body.

post/esims/{id}/topups

Request

  • Base URL: https://dashboard.voidmob.com/api/v1
  • URL: https://dashboard.voidmob.com/api/v1/esims/{id}/topups
  • Auth: HTTP bearer

Path parameters

idstring required

Headers

Idempotency-Keystring required
Example:7c4f08c2-2a4f-4c8e-a1d2-9c2b9c8f7e10

Client-supplied key (any string, up to 255 chars) that scopes idempotent replay for write requests. Required on every POST, PATCH, and DELETE. Replays with the same key + same body return the cached response; same key with a different body returns IDEMPOTENCY_CONFLICT. Headers are case-insensitive; both Idempotency-Key and idempotency-key work.

Request body

product_idstring required

Public product id (prefixed prod_) from the eSIM catalog.

max_price_centsinteger

Optional price ceiling in USD cents. If the current price exceeds this value the call returns 409 PRICE_OVER_CAP. Omit to accept any price.

parent_order_idstring

Public id of the eSIM to top up (prefixed esim_). Any order on that eSIM is accepted - a topup id resolves to the base order it sits on. Ignored on POST /esims/{id}/topups where the path parameter takes precedence.

webhook_endpoint_idstring

If set, scope this order's webhook events to this endpoint only.

Example request

{
  "product_id": "prod_abc123",
  "parent_order_id": "esim_01HXYZ000ABC",
  "webhook_endpoint_id": "whep_01HXYZ123ABC"
}

Response

Topup purchased. Returns the new eSIM topup order.

successtrue required

Example response

{
  "data": {
    "esim": {
      "id": "esim_01HXYZ123ABC",
      "product_id": "prod_abc123",
      "parent_order_id": "esim_01HXYZ000ABC",
      "iccid": "89012345678901234567",
      "activation_code": "K2-2VOZBJ-22QT3D",
      "qr_code_url": "https://dashboard.voidmob.com/api/v1/esims/esim_01HXYZ123ABC/qr.png",
      "smdp_address": "smdp.io",
      "data_limit_gb": 10,
      "validity_days": 30,
      "countries": [
        "DE",
        "FR",
        "IT"
      ],
      "charged_price_cents": 1500
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.