Skip to main content
What changed in the API’s behaviour, newest first. Price changes are not listed here — they come by email, as your agreement sets out. Subscribe to the RSS feed to hear about changes as they ship.
​
Refund requests, webhook event field
  • New: Request a refund — POST /v1/api_partner/esims/{topup_id}/refund opens a refund request and answers 202. Get a refund request reads it back. Both share a limit of 30 requests per minute.
  • New: refund decisions arrive on your webhook URL as refund.approved or refund.rejected, only for requests you open through the API. See Refund events.
  • Every webhook body now starts with an event field — esim.issued for eSIM deliveries, ahead of their existing fields, which are unchanged. The X-Esim-Story-Event header repeats it. Branch on the body field: the signature covers the body, not the headers. See Webhooks.
​
Product list endpoint
New: List products — GET /v1/api_partner/products returns every product you can order, with its option_id, specification and your wholesale price. Filter by country (ISO code), location_type or location. Limited to 10 requests per minute; fetch it daily and cache it.Unlimited plans report data_mb as 5120, the full-speed part of each day.
​
QR images on our own domain
qrcode_img_url now points to assets.esimstory.com. The URL is opaque: don’t parse it or depend on its host. download_link is the durable value, and you can render your own QR from it. See Payload.
​
eSIM status, order size limit, webhook payload
  • New: Get eSIM status — GET /v1/api_partner/esims/{topup_id}/status reports installation, data used and expiry. Limited to 60 requests per minute.
  • One order now carries at most 100 eSIMs in total.
  • Webhook payloads now carry a fixed, documented set of fields. See Payload.
  • In sandbox, the test eSIM now arrives later through the webhook, the same way as in production.
​
Signed bodies and signed, retried webhooks
  • Breaking: the request signature now covers a SHA-256 hash of the body, so the signed string has five lines. See Authentication.
  • Webhooks are signed. Verify each delivery before processing it — see Verifying the signature.
  • Failed webhook deliveries are retried up to 10 times over about four and a half hours. The same topup_id can arrive more than once.
​
Validation errors
A malformed order payload returns 422 with an errors array.
Last modified on November 2, 2026