> ## Documentation Index
> Fetch the complete documentation index at: https://docs.esimmu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get eSIM status

> Installation, activation and refund eligibility for one eSIM, read live from the network. The `data_*` fields are for the current day: every plan resets daily, and `data_total_mb` is the daily allowance. For usage over the whole plan, use Get eSIM usage.

Installation, activation and refund eligibility for one eSIM, read live from
the network on every call.

> [!NOTE]
>
> The `data_*` fields cover **today only**. Every plan resets daily, and
> `data_total_mb` is the daily allowance. For usage across the whole plan, use
> [Get eSIM usage](https://docs.esimmu.com/endpoints/esim-usage.md).

## Statuses

| `status` | Meaning |
| - | - |
| `not_installed` | Issued, not yet installed on a device |
| `installed` | Installed, not yet connected to a network |
| `activated` | In use; the plan is running |
| `expired` | The plan has ended |
| `activation_expired` | Not installed before `activation_expiration_at`; can no longer be used |
| `refunded` | Refunded |

`refundable` is `true` only while the eSIM is not installed, not refunded, and
inside its activation window. When it is `false`, `non_refundable_reason` says
which of those failed. Check it before you [request a
refund](https://docs.esimmu.com/endpoints/request-refund.md).


## OpenAPI

````yaml GET /v1/api_partner/partner_order_items/{topup_id}
openapi: 3.1.0
info:
  title: eSIMmu API
  version: 1.0.0
  summary: Order eSIMs from your own systems over HTTP.
  description: >-
    Server-to-server API for eSIMmu API partners.


    **Ordering is asynchronous.** `POST /v1/api_partner/orders` returns `201`
    with one `topup_id` per unit ordered; the eSIM activation data itself
    arrives later as one `esim.issued` webhook per unit. There is no endpoint to
    poll for it.


    **Every request is signed.** Three headers carry an HMAC-SHA256 proof; see
    the `esimmuAccessKey`, `esimmuSignature` and `esimmuTimestamp` security
    schemes, and the Authentication guide for the full recipe and a test vector.


    **The path you sign is not the path in this document.** Paths here are
    relative to the server URL, which already ends in `/api`. The signature
    covers the full request path *including* that prefix:
    `/api/v1/api_partner/orders`, not `/v1/api_partner/orders`.


    **Product IDs (`option_id`) come from `GET /v1/api_partner/products`**, the
    catalogue at your own price. Fetch it daily and cache it.


    **There is no sandbox yet.**
servers:
  - url: https://api.esimmu.com/api
    description: Production
security:
  - esimmuAccessKey: []
    esimmuSignature: []
    esimmuTimestamp: []
tags:
  - name: Products
  - name: Orders
  - name: Refunds
paths:
  /v1/api_partner/partner_order_items/{topup_id}:
    get:
      tags:
        - Orders
      summary: Get eSIM status
      description: >-
        Installation, activation and refund eligibility for one eSIM, read live
        from the network. The `data_*` fields are for the current day: every
        plan resets daily, and `data_total_mb` is the daily allowance. For usage
        over the whole plan, use Get eSIM usage.
      operationId: getEsimStatus
      parameters:
        - $ref: '#/components/parameters/TopupId'
      responses:
        '200':
          description: The eSIM's current state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsimStatus'
              example:
                created_at: '2026-11-16T03:00:00Z'
                installed_at: '2026-11-17T09:12:44Z'
                activated_at: '2026-11-18T01:05:10Z'
                expires_at: '2026-11-25T01:05:10Z'
                device_name: iPhone 15 Plus
                install_count: 1
                eid: '89049032000001000000123456789012'
                data_total_mb: 1024
                data_used_mb: 348.2
                data_remaining_mb: 675.8
                refundable: false
                non_refundable_reason: esim_installed
                status: activated
                activation_expiration_at: '2027-05-15'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ProviderFailed'
components:
  parameters:
    TopupId:
      name: topup_id
      in: path
      required: true
      description: The eSIM, as returned by Create an order and sent in `esim.issued`.
      schema:
        type: string
      example: '202611161200000000000001'
  schemas:
    EsimStatus:
      type: object
      properties:
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        installed_at:
          type:
            - string
            - 'null'
          format: date-time
        activated_at:
          type:
            - string
            - 'null'
          format: date-time
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the plan ends, once activated.
        device_name:
          type:
            - string
            - 'null'
        install_count:
          type:
            - integer
            - 'null'
        eid:
          type:
            - string
            - 'null'
        data_total_mb:
          type: number
          description: Today's allowance. Plans reset daily.
        data_used_mb:
          type: number
          description: Used today.
        data_remaining_mb:
          type: number
          description: Left today.
        refundable:
          type: boolean
          description: >-
            Whether a refund request can still succeed: not installed, not
            refunded, activation window open.
        non_refundable_reason:
          type:
            - string
            - 'null'
          enum:
            - refunded
            - esim_installed
            - activation_expired
            - null
        status:
          type: string
          enum:
            - not_installed
            - installed
            - activated
            - expired
            - activation_expired
            - refunded
        activation_expiration_at:
          type:
            - string
            - 'null'
          format: date
          description: >-
            Last day to install and activate. After it the eSIM can no longer be
            used.
    AuthError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              const: unauthorized
            message:
              type: string
    ErrorList:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
  responses:
    Unauthorized:
      description: Signing failed. See Authentication for each message.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthError'
          example:
            error:
              code: unauthorized
              message: Invalid signature.
    NotFound:
      description: No eSIM with that `topup_id` on your account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorList'
          example:
            errors:
              - eSIM not found
    ProviderFailed:
      description: The network could not be reached. Retry later.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorList'
          example:
            errors:
              - eSIM provider request failed. Please retry later.
  securitySchemes:
    esimmuAccessKey:
      type: apiKey
      in: header
      name: X-Esimmu-Access-Key
      description: Your partner access key. Identifies you on every request.
    esimmuSignature:
      type: apiKey
      in: header
      name: X-Esimmu-Signature
      description: >-
        Lowercase hex HMAC-SHA256 over the five-line string
        `{METHOD}\n{REQUEST_PATH}\n{TIMESTAMP}\n{ACCESS_KEY}\n{BODY_SHA256}`,
        keyed with your **Base64-decoded** secret key.


        `REQUEST_PATH` includes the `/api` prefix and excludes the domain and
        any query string. `BODY_SHA256` is the lowercase hex SHA-256 of the
        exact body bytes you send; for a request with no body, hash the empty
        string. The string always has five lines.
    esimmuTimestamp:
      type: apiKey
      in: header
      name: X-Esimmu-Timestamp
      description: Unix seconds (UTC), within 5 minutes of our clock.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.