openapi: 3.0.1
info:
  title: Maya Mobile Connect+ Connectivity eSIMs Orders API
  description: 'Maya Mobile (Mobile Maya Inc) Connect+ Connectivity REST API for provisioning eSIMs and data packages, monitoring activation status and data usage, processing top-ups, and receiving lifecycle events via webhooks across 400+ roaming networks in 200+ destinations.


    NOTE: Maya Mobile distributes the full Connectivity API reference under NDA to onboarded resellers and partners. This document models the publicly described capabilities of the Connect+ API (eSIM provisioning, data packages/plans, status and usage, top-ups, orders, and webhooks). Exact endpoint paths, request/response schemas, and authentication parameters are confirmed against the partner documentation during onboarding and are not fully published. Paths below reflect the documented capability surface and are marked as unreconciled where exact shapes are not public.'
  termsOfService: https://maya.net/terms
  contact:
    name: Maya Mobile Partnerships
    url: https://maya.net/business
  version: '1.0'
servers:
- url: https://api.maya.net/connectivity/v1
  description: Connect+ Connectivity API base URL (representative; confirm exact host and version path against partner documentation during onboarding).
security:
- bearerAuth: []
tags:
- name: Orders
  description: Placing and assigning data-package orders, including top-ups.
paths:
  /esims/{esimId}/topup:
    post:
      operationId: topupEsim
      tags:
      - Orders
      summary: Top up an eSIM
      description: Adds (tops up) an additional data package to an existing eSIM for the specified country, region, or network.
      parameters:
      - name: esimId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopupRequest'
      responses:
        '201':
          description: The resulting order/top-up.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
  /orders:
    post:
      operationId: createOrder
      tags:
      - Orders
      summary: Create a data-package order
      description: Places a data-package order and assigns it to an eSIM for specific countries, regions, and networks. Supports one or multiple packages.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: The created order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
    get:
      operationId: listOrders
      tags:
      - Orders
      summary: List orders
      description: Lists previously placed data-package orders.
      responses:
        '200':
          description: A list of orders.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
        esim_id:
          type: string
        status:
          type: string
        items:
          type: array
          items:
            type: object
            properties:
              plan_id:
                type: string
              quantity:
                type: integer
    CreateOrderRequest:
      type: object
      properties:
        esim_id:
          type: string
          description: Target eSIM to assign the package(s) to.
        items:
          type: array
          items:
            type: object
            properties:
              plan_id:
                type: string
              quantity:
                type: integer
      required:
      - items
    TopupRequest:
      type: object
      properties:
        plan_id:
          type: string
        country:
          type: string
        region:
          type: string
      required:
      - plan_id
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token / API key supplied in the Authorization header (`Authorization: Bearer <token>`). Credentials are issued to onboarded Maya Mobile resellers/partners.'