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

# List products

> Every product you can order, with what it covers and your wholesale price: the price you are invoiced for it. Fetch it once a day and cache it, rather than per order. Limited to 10 requests per minute per access key.

The filters narrow the list; an unknown value returns an empty list, not the whole catalogue.

Every product you can order, with what it covers and your wholesale price: the
price you are invoiced for it. The `option_id` values here are what [Create an
order](https://docs.esimmu.com/endpoints/create-order.md) takes.

It lists what is on sale. A destination we are preparing, or have paused, is
left out until it is on sale.

**Fetch it once a day and cache it**, rather than per order or per page view.
It returns the whole catalogue, about 11,000 rows, gzipped when your client
accepts it.

## Filters

All optional. Without them you get the whole catalogue.

* `country`: an ISO code such as `JP`. Returns Japan's own plans **and** every
  regional plan that covers Japan.
* `location_type`: `country` or `region`.
* `location`: a name exactly as the response spells it, such as `Japan`. Case
  does not matter.

An unknown value returns an empty list, not the whole catalogue, so a typo
shows up as no results rather than as everything.

## Reading a row

* `data` is the daily allowance as a person reads it. Unlimited plans read
  `Unlimited`; their `data_mb` is the full-speed part each day.
* `countries` lists where the plan works: the country itself, or each country a
  region covers, with its ISO code.
* `wholesale_price_usd` is a string with two decimals, so it never arrives as a
  float.

## Keeping your catalogue in sync

If you keep your own copy of the catalogue, for example to show plans or prices
in your storefront, sync it once a day:

1. **Fetch the whole list** without filters, with `Accept-Encoding: gzip`.
2. **Key every row on `option_id`.** It is stable for a product and is what you
   order with.
3. **Upsert.** Add the `option_id` values you have not seen, and update the
   ones you have. `wholesale_price_usd` is what you will be invoiced from then
   on, so compare it with what you stored and act on changes, such as
   repricing your own plan or flagging it for review.
4. **Stop selling what is gone.** An `option_id` that is no longer in the list
   is no longer on sale. Stop offering it to your customers.

A failed fetch should leave your last good copy in place rather than empty it.

## Rate limit

**10 requests per minute** per access key. Going over returns `429 Too Many
Requests` with a `Retry-After` header in seconds.


## OpenAPI

````yaml GET /v1/api_partner/products
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/products:
    get:
      tags:
        - Products
      summary: List products
      description: >-
        Every product you can order, with what it covers and your wholesale
        price: the price you are invoiced for it. Fetch it once a day and cache
        it, rather than per order. Limited to 10 requests per minute per access
        key.


        The filters narrow the list; an unknown value returns an empty list, not
        the whole catalogue.
      operationId: listProducts
      parameters:
        - name: country
          in: query
          required: false
          description: >-
            An ISO 3166-1 alpha-2 code, such as `JP`. Returns the country's own
            plans and every regional plan that covers it.
          schema:
            type: string
          example: JP
        - name: location_type
          in: query
          required: false
          description: '`country` or `region`.'
          schema:
            type: string
            enum:
              - country
              - region
        - name: location
          in: query
          required: false
          description: >-
            A country or region name exactly as the response spells it, such as
            `Japan`. Case does not matter.
          schema:
            type: string
      responses:
        '200':
          description: The catalogue, or the part the filters select.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'
              example:
                products:
                  - option_id: A1B2C3D4-E5F6-7890-ABCD-EF1234567890
                    location_type: country
                    location: Japan
                    countries:
                      - name: Japan
                        iso_code: JP
                    duration_days: 5
                    data: 1GB
                    data_mb: 1024
                    carrier: SoftBank
                    qos: 384kbps
                    network: 4G / 5G
                    activation_window_days: 180
                    apn: plus.4g
                    wholesale_price_usd: '3.80'
                  - option_id: B2C3D4E5-F6A7-8901-BCDE-F12345678901
                    location_type: region
                    location: Asia (13 Countries)
                    countries:
                      - name: Japan
                        iso_code: JP
                      - name: South Korea
                        iso_code: KR
                    duration_days: 7
                    data: Unlimited
                    data_mb: 5120
                    carrier: Local carriers (13 countries)
                    qos: 1Mbps
                    network: 4G
                    activation_window_days: 180
                    apn: plus.4g
                    wholesale_price_usd: '23.00'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          description: >-
            More than 10 requests in a minute on this access key. Wait the
            number of seconds in `Retry-After`.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorList'
              example:
                errors:
                  - Too many requests. Please try again shortly.
components:
  schemas:
    ProductList:
      type: object
      properties:
        products:
          type: array
          items:
            $ref: '#/components/schemas/Product'
    ErrorList:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
    Product:
      type: object
      properties:
        option_id:
          type: string
          description: What Create an order takes as `option_id`.
        location_type:
          type: string
          enum:
            - country
            - region
        location:
          type: string
          description: The country or region name.
        countries:
          type: array
          description: >-
            Where the plan works: the country itself, or each country a region
            covers.
          items:
            type: object
            properties:
              name:
                type: string
              iso_code:
                type:
                  - string
                  - 'null'
                description: ISO 3166-1 alpha-2.
        duration_days:
          type: integer
        data:
          type: string
          description: >-
            Daily allowance as a person reads it, such as `1GB`; `Unlimited` for
            unlimited plans.
        data_mb:
          type: integer
          description: >-
            Daily allowance in MB. On unlimited plans, the full-speed part
            before the speed drops.
        carrier:
          type:
            - string
            - 'null'
        qos:
          type:
            - string
            - 'null'
          description: Speed after the daily allowance is used.
        network:
          type:
            - string
            - 'null'
        activation_window_days:
          type:
            - integer
            - 'null'
          description: Days from purchase to install and activate.
        apn:
          type:
            - string
            - 'null'
        wholesale_price_usd:
          type: string
          description: >-
            What you are invoiced for one eSIM, in USD, as a string with two
            decimals.
    AuthError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              const: unauthorized
            message:
              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.
  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.