{"openapi":"3.1.0","info":{"title":"esimker API","description":"Prepaid travel data eSIMs. No accounts: an order is addressed by the\nsecret token from its URL. Prices are USD strings, from $1.00.\n\nTwo ways to buy:\n\n- **Storefront flow** (`catalog`, `orders`): pick a plan, `POST /api/orders`, send the\n  buyer to `checkout_url` to pay by card or crypto, then poll `GET /api/orders/{token}`\n  until `status` is `ready` — the eSIM (`esim.activation_code`) is in the payload.\n- **Prepaid wallet** (`wallet`): `POST /api/wallet` mints a wallet whose secret code is\n  the only credential (`X-Wallet-Code`); `POST /api/wallet/deposits` opens a top-up\n  invoice and, with `currency` set, returns the coin address and the exact amount for a\n  payer with no browser; `POST /api/orders` with `payment_method: \"wallet\"` charges the\n  balance and issues at once (`client_ref` makes a retry return the same order).\n- **Reseller API** (`reseller`): white-label partners on `X-API-Key`, retail minus a\n  discount; keys are issued by support.\n\nThe wallet and the catalogue are also MCP tools at `POST https://esimker.com/api/mcp`\n(Streamable HTTP; the wallet code goes in `Authorization: Bearer`).\n\nThe guide for agents is https://esimker.com/agents (the wallet: https://esimker.com/agents#wallet).","version":"1"},"paths":{"/api/catalog":{"get":{"tags":["catalog"],"summary":"Catalog Index","description":"Destinations on sale with the lowest price and the plan count; `slug` is\nthe key for `GET /api/catalog/{slug}`.","operationId":"catalog_index_api_catalog_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Response Catalog Index Api Catalog Get"}}}}}}},"/api/catalog/{slug}":{"get":{"tags":["catalog"],"summary":"Catalog Destination","description":"The destination's plans (`plans[].id` is the `plan_id` for an order) and its\npublished reviews.","operationId":"catalog_destination_api_catalog__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Catalog Destination Api Catalog  Slug  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/orders":{"post":{"tags":["orders"],"summary":"Create Order","description":"Create an unpaid order and its checkout. Open `checkout_url` to pay (card or\ncrypto, hosted by the gateway); the order page is `/order?t={token}`. 403 from\nembargoed jurisdictions, 10 orders per minute per IP.","operationId":"create_order_api_orders_post","parameters":[{"name":"X-Wallet-Code","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Wallet-Code"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/payment-methods":{"get":{"tags":["orders"],"summary":"Payment Methods","description":"Which checkout methods the storefront and the bot may offer right now.\n\n`gateways` names the providers behind each method, best first, for a caller\nthat lets the buyer choose one (`payment_gateway` on POST /api/orders).\nIgnoring it is fine — the first of them is what an unspecified checkout gets.","operationId":"payment_methods_api_payment_methods_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Payment Methods Api Payment Methods Get"}}}}}}},"/api/orders/{token}":{"get":{"tags":["orders"],"summary":"Get Order","description":"Order status by its secret token; `ready` orders carry `esim.activation_code`.","operationId":"get_order_api_orders__token__get","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Order Api Orders  Token  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/orders/{token}/claim":{"post":{"tags":["orders"],"summary":"Claim Gift","description":"The gift recipient activates the eSIM — provisioning starts here.","operationId":"claim_gift_api_orders__token__claim_post","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"},"title":"Response Claim Gift Api Orders  Token  Claim Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/orders/{token}/email":{"post":{"tags":["orders"],"summary":"Resend Email","description":"(Re)send the eSIM to an email — also covers \"email me this\" on the order page.","operationId":"resend_email_api_orders__token__email_post","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendEmailIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"boolean"},"title":"Response Resend Email Api Orders  Token  Email Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/orders/{token}/review":{"get":{"tags":["orders"],"summary":"Review State","description":"Whether this order may still be reviewed — drives the form on the order page.","operationId":"review_state_api_orders__token__review_get","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"boolean"},"title":"Response Review State Api Orders  Token  Review Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["orders"],"summary":"Create Review","description":"A buyer rates a delivered order. Held as `pending` until an admin publishes it.","operationId":"create_review_api_orders__token__review_post","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"},"title":"Response Create Review Api Orders  Token  Review Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/promo/{code}":{"get":{"tags":["orders"],"summary":"Check Promo","description":"Live promo validation for the checkout UI.","operationId":"check_promo_api_promo__code__get","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","title":"Code"}},{"name":"plan_id","in":"query","required":true,"schema":{"type":"integer","title":"Plan Id"}},{"name":"period_num","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Period Num"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Check Promo Api Promo  Code  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/reseller/me":{"get":{"tags":["reseller"],"summary":"Me","description":"The wallet behind the key: name, balance and the discount off retail.","operationId":"me_api_reseller_me_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Me Api Reseller Me Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/reseller/packages":{"get":{"tags":["reseller"],"summary":"Packages","description":"Every active data plan with the wallet's price. `daily_unlimited` plans are\npriced per day and take `period_num` on the order. Re-fetch at least daily.","operationId":"packages_api_reseller_packages_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true},"title":"Response Packages Api Reseller Packages Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/reseller/orders":{"post":{"tags":["reseller"],"summary":"Create Order","description":"Charge the wallet and issue an eSIM. 402 when the balance is short. Send\nyour own `external_id`: a repeat POST with the same value returns the existing\norder instead of charging twice. The order comes back `paid`; poll\n`GET /api/reseller/orders/{token}` for `ready` and the activation code.","operationId":"create_order_api_reseller_orders_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerOrderIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Order Api Reseller Orders Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/reseller/orders/{token}":{"get":{"tags":["reseller"],"summary":"Get Order","description":"The order; once `status` is `ready` it carries `esim.activation_code`.","operationId":"get_order_api_reseller_orders__token__get","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Order Api Reseller Orders  Token  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/support/tickets":{"post":{"tags":["support"],"summary":"Create Ticket","operationId":"create_ticket_api_support_tickets_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/topups/{iccid}":{"get":{"tags":["topups"],"summary":"List Topups","description":"Available top-ups for an ICCID: EA provides compatibility, prices come from our plans.","operationId":"list_topups_api_topups__iccid__get","parameters":[{"name":"iccid","in":"path","required":true,"schema":{"type":"string","pattern":"^89\\d{16,20}$","title":"Iccid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true},"title":"Response List Topups Api Topups  Iccid  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/usage/{iccid}":{"get":{"tags":["topups"],"summary":"Get Usage","description":"Remaining data. Only for eSIMs issued by us.","operationId":"get_usage_api_usage__iccid__get","parameters":[{"name":"iccid","in":"path","required":true,"schema":{"type":"string","pattern":"^89\\d{16,20}$","title":"Iccid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Usage Api Usage  Iccid  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/wallet":{"post":{"tags":["wallet"],"summary":"Create","operationId":"create_api_wallet_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWalletIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecretOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["wallet"],"summary":"Read","operationId":"read_api_wallet_get","parameters":[{"name":"X-Wallet-Code","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Wallet-Code"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Read Api Wallet Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/wallet/connect":{"post":{"tags":["wallet"],"summary":"Connect","description":"Opens a wallet by its code or its backup phrase, and hands back both\nforms — the phrase is how a wallet opened by code gets its backup shown.","operationId":"connect_api_wallet_connect_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecretOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/wallet/deposits":{"post":{"tags":["wallet"],"summary":"Deposit","description":"A top-up: the same providers and the same webhooks as an order, only the\nthing being paid for is credit. The pay page sends the buyer back to the\nwallet page with the deposit's token, which the page then reports on.","operationId":"deposit_api_wallet_deposits_post","parameters":[{"name":"X-Wallet-Code","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Wallet-Code"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/wallet/deposits/{token}":{"get":{"tags":["wallet"],"summary":"Deposit Status","description":"Polled by the wallet page after the pay page sends the buyer back —\nthe webhook usually lands before they do, but not always.","operationId":"deposit_status_api_wallet_deposits__token__get","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}},{"name":"X-Wallet-Code","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Wallet-Code"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Deposit Status Api Wallet Deposits  Token  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ConnectIn":{"properties":{"secret":{"type":"string","maxLength":400,"minLength":1,"title":"Secret"}},"type":"object","required":["secret"],"title":"ConnectIn"},"CreateOrderIn":{"properties":{"plan_id":{"type":"integer","title":"Plan Id"},"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Email"},"topup_iccid":{"anyOf":[{"type":"string","pattern":"^89\\d{16,20}$"},{"type":"null"}],"title":"Topup Iccid"},"promo_code":{"anyOf":[{"type":"string","pattern":"^[A-Za-z0-9_-]{2,32}$"},{"type":"null"}],"title":"Promo Code"},"referral_code":{"anyOf":[{"type":"string","pattern":"^[A-Za-z0-9_-]{2,32}$"},{"type":"null"}],"title":"Referral Code"},"gift":{"type":"boolean","title":"Gift","default":false},"lang":{"anyOf":[{"type":"string","pattern":"^[A-Za-z]{2}(-[A-Za-z]{4})?$"},{"type":"null"}],"title":"Lang"},"payment_method":{"type":"string","pattern":"^(crypto|card|wallet)$","title":"Payment Method","default":"crypto"},"payment_gateway":{"anyOf":[{"type":"string","pattern":"^[a-z][a-z0-9_-]{1,30}$"},{"type":"null"}],"title":"Payment Gateway"},"period_num":{"anyOf":[{"type":"integer","maximum":365.0,"minimum":1.0},{"type":"null"}],"title":"Period Num"},"client_ref":{"anyOf":[{"type":"string","maxLength":64,"minLength":1},{"type":"null"}],"title":"Client Ref"}},"type":"object","required":["plan_id"],"title":"CreateOrderIn"},"CreateOrderOut":{"properties":{"token":{"type":"string","title":"Token"},"checkout_url":{"type":"string","title":"Checkout Url"}},"type":"object","required":["token","checkout_url"],"title":"CreateOrderOut"},"CreateWalletIn":{"properties":{"accept_terms":{"type":"boolean","title":"Accept Terms"}},"type":"object","required":["accept_terms"],"title":"CreateWalletIn"},"DepositIn":{"properties":{"amount_usd":{"anyOf":[{"type":"number","maximum":100000.0,"exclusiveMinimum":0.0},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"}],"title":"Amount Usd"},"payment_method":{"type":"string","pattern":"^(crypto|card)$","title":"Payment Method","default":"crypto"},"payment_gateway":{"anyOf":[{"type":"string","pattern":"^[a-z][a-z0-9_-]{1,30}$"},{"type":"null"}],"title":"Payment Gateway"},"lang":{"anyOf":[{"type":"string","pattern":"^[A-Za-z]{2}(-[A-Za-z]{4})?$"},{"type":"null"}],"title":"Lang"},"currency":{"anyOf":[{"type":"string","pattern":"^[A-Za-z0-9]{2,16}$"},{"type":"null"}],"title":"Currency"}},"type":"object","required":["amount_usd"],"title":"DepositIn"},"DepositOut":{"properties":{"deposit":{"additionalProperties":true,"type":"object","title":"Deposit"},"checkout_url":{"type":"string","title":"Checkout Url"},"pay":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Pay"}},"type":"object","required":["deposit","checkout_url"],"title":"DepositOut"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ResellerOrderIn":{"properties":{"plan_id":{"type":"integer","title":"Plan Id"},"external_id":{"anyOf":[{"type":"string","maxLength":64,"minLength":1},{"type":"null"}],"title":"External Id"},"period_num":{"anyOf":[{"type":"integer","maximum":365.0,"minimum":1.0},{"type":"null"}],"title":"Period Num"}},"type":"object","required":["plan_id"],"title":"ResellerOrderIn"},"ResendEmailIn":{"properties":{"email":{"type":"string","format":"email","title":"Email"}},"type":"object","required":["email"],"title":"ResendEmailIn"},"ReviewIn":{"properties":{"rating":{"type":"integer","maximum":5.0,"minimum":1.0,"title":"Rating"},"text":{"type":"string","maxLength":1000,"title":"Text","default":""},"author":{"type":"string","maxLength":64,"title":"Author","default":""}},"type":"object","required":["rating"],"title":"ReviewIn"},"SecretOut":{"properties":{"code":{"type":"string","title":"Code"},"phrase":{"type":"string","title":"Phrase"},"wallet":{"additionalProperties":true,"type":"object","title":"Wallet"}},"type":"object","required":["code","phrase","wallet"],"title":"SecretOut"},"TicketIn":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"message":{"type":"string","maxLength":5000,"title":"Message"},"topic":{"type":"string","pattern":"^(order|esim|refund|other)$","title":"Topic","default":"other"},"order_ref":{"type":"string","maxLength":255,"title":"Order Ref","default":""},"lang":{"anyOf":[{"type":"string","pattern":"^[A-Za-z]{2}(-[A-Za-z]{4})?$"},{"type":"null"}],"title":"Lang"},"website":{"type":"string","maxLength":255,"title":"Website","default":""}},"type":"object","required":["email","message"],"title":"TicketIn"},"TicketOut":{"properties":{"key":{"type":"string","title":"Key"}},"type":"object","required":["key"],"title":"TicketOut"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}