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

# Create an order

> Orders one or more eSIMs. Returns one `topup_id` per unit; the eSIM data for each arrives on your webhook as `esim.issued`.

Safe to retry: sending the same `external_order_id` again returns the original order instead of placing a new one.

Orders one or more eSIMs. The `201` lists one `topup_id` per unit; each eSIM's
activation data then arrives on your webhook as
[`esim.issued`](https://docs.esimmu.com/endpoints/webhooks).

## Retrying an order

`external_order_id` is your idempotency key. Sending an order again with the
same `external_order_id` returns the original order rather than placing a new
one, so when a request times out or answers `5xx` or a provider `422`, retry it
as it was.

* Keep the same `external_order_id` and products on a retry.
* Use a new `external_order_id` only for a genuinely new order.
* Another partner using the same value does not affect you: it is unique
  within your account only.

## Errors

| Status | Example | What to do |
| - | - | - |
| `400` | `{"error": "unexpected character: ..."}` | Send valid JSON |
| `401` | `{"error": {"code": "unauthorized", "message": "Invalid signature."}}` | See [Authentication](https://docs.esimmu.com/authentication/overview.md#errors) |
| `422` | `{"errors": ["products[0].option_id is not a known product"]}` | Fix the field named in the message |
| `422` | `{"errors": ["eSIM provider request failed. Please retry later."]}` | Retry with the same `external_order_id` |

The field messages you can get:

* `external_order_id must be 1-64 characters of letters, digits, '-' or '_'`
* `products must be a non-empty array`
* `products[N] must be an object`
* `products[N].qty must be a positive integer`
* `products[N].option_id is not a known product`


## OpenAPI

````yaml POST /v1/api_partner/orders
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/orders:
    post:
      tags:
        - Orders
      summary: Create an order
      description: >-
        Orders one or more eSIMs. Returns one `topup_id` per unit; the eSIM data
        for each arrives on your webhook as `esim.issued`.


        Safe to retry: sending the same `external_order_id` again returns the
        original order instead of placing a new one.
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
            example:
              external_order_id: ORD-1001
              products:
                - option_id: A1B2C3D4-E5F6-7890-ABCD-EF1234567890
                  qty: 2
      responses:
        '201':
          description: Order accepted. One entry in `products` per unit ordered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
              example:
                external_order_id: ORD-1001
                products:
                  - option_id: A1B2C3D4-E5F6-7890-ABCD-EF1234567890
                    topup_id: '202611161200000000000001'
                  - option_id: A1B2C3D4-E5F6-7890-ABCD-EF1234567890
                    topup_id: '202611161200000000000002'
        '400':
          $ref: '#/components/responses/BadJson'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: >-
            The order cannot be placed: a field is invalid (the message names
            it), or the eSIM provider failed, in which case retry with the same
            `external_order_id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorList'
              examples:
                invalidField:
                  value:
                    errors:
                      - products[0].option_id is not a known product
                providerFailed:
                  value:
                    errors:
                      - eSIM provider request failed. Please retry later.
components:
  schemas:
    CreateOrderRequest:
      type: object
      required:
        - external_order_id
        - products
      properties:
        external_order_id:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
          description: >-
            Your own reference for the order, unique within your account.
            Sending it again returns the original order instead of placing a new
            one, so it is safe to retry with.
        products:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ProductLine'
    CreateOrderResponse:
      type: object
      required:
        - external_order_id
        - products
      properties:
        external_order_id:
          type: string
        products:
          type: array
          description: One entry per unit ordered.
          items:
            $ref: '#/components/schemas/OrderedUnit'
    ErrorList:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
    ProductLine:
      type: object
      required:
        - option_id
        - qty
      properties:
        option_id:
          type: string
          description: A product from the product list we send you.
        qty:
          type: integer
          minimum: 1
          description: Number of eSIMs of this product.
    OrderedUnit:
      type: object
      required:
        - option_id
        - topup_id
      properties:
        option_id:
          type: string
        topup_id:
          type: string
          description: The eSIM. Keys every later call and webhook about it.
    ParseError:
      type: object
      properties:
        error:
          type: string
    AuthError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              const: unauthorized
            message:
              type: string
  responses:
    BadJson:
      description: >-
        The body is not valid JSON. The message is the parser's; its wording is
        not stable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ParseError'
          example:
            error: 'unexpected character: ''products'' at line 1 column 2'
    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.