esimker Orders API

openapi: 3.2.0
info:
  title: esimker Orders API
  description: 'Prepaid travel data eSIMs. No account is needed: an order is addressed by

    the secret token from its URL. Prices are USD strings, from $1.00.


    Two ways to buy:


    - **Storefront flow** (`catalog`, `orders`): pick a plan, `POST /api/orders`, send the

    buyer to `checkout_url` to pay in crypto, then poll `GET /api/orders/{token}`

    until `status` is `ready` — the eSIM (`esim.activation_code`) is in the payload.

    - **Prepaid wallet** (`wallet`): `POST /api/wallet` mints a wallet whose secret code is

    the only credential (`X-Wallet-Code`); `POST /api/wallet/deposits` opens a top-up

    invoice and, with `currency` set, returns the coin address and the exact amount for a

    payer with no browser; `POST /api/orders` with `payment_method: "wallet"` charges the

    balance and issues at once (`client_ref` makes a retry return the same order).

    - **Reseller API** (`reseller`): white-label partners on `X-API-Key`, retail minus a

    discount; keys are issued by support.


    The wallet and the catalogue are also MCP tools at `POST https://esimker.com/api/mcp`

    (Streamable HTTP; the wallet code goes in `Authorization: Bearer`).


    The guide for agents is https://esimker.com/agents (the wallet: https://esimker.com/agents#wallet).


    **Buyer accounts** (`account`) are the storefront''s own cabinet: an address and a password

    as a second way for a person to reach their orders and wallets, on a session cookie with a

    CSRF echo. An account is optional and nothing above needs one — an agent keeps the order

    token and the wallet code, and has no use for these routes.'
  version: '1'
tags:
- name: Orders
paths:
  /api/orders:
    post:
      tags:
      - Orders
      summary: Create Order
      description: 'Create an unpaid order and its checkout. Open `checkout_url` to pay (card or

        crypto, hosted by the gateway); the order page is `/order?t={token}`. 403 from

        embargoed 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.


        `gateways` names the providers behind each method, best first, for a caller

        that lets the buyer choose one (`payment_gateway` on POST /api/orders).

        Ignoring 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.


        Counted per IP like the writes are, and for the same reason: it is free,

        anonymous and answers yes or no about a short code, which is the whole of

        what a guesser needs. And it answers "no" the one way — see PromoError.'
      operationId: check_promo_api_promo__code__get
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{2,32}$
          title: Code
      - name: plan_id
        in: query
        required: true
        schema:
          type: integer
          maximum: 2147483647
          minimum: 1
          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'
components:
  schemas:
    ResendEmailIn:
      properties:
        email:
          type: string
          format: email
          title: Email
      type: object
      required:
      - email
      title: ResendEmailIn
    CreateOrderOut:
      properties:
        token:
          type: string
          title: Token
        checkout_url:
          type: string
          title: Checkout Url
      type: object
      required:
      - token
      - checkout_url
      title: CreateOrderOut
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CreateOrderIn:
      properties:
        plan_id:
          type: integer
          maximum: 2147483647.0
          minimum: 1.0
          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
    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
    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