ONYX
Docs

Services And Usage API

List active service records, retrieve one service, and check package usage.

Services And Usage API helps partners review active service records and data consumption.

Use it to answer customer questions, confirm install state, monitor data remaining, and support reconciliation after an order becomes ready.

Usage is the latest available report. It can trail live device activity because network reporting, device activity, and service state affect timing.

List Services

GET /v1/partner/esims

Returns service records available to your partner account.

{
  "data": {
    "esims": [
      {
        "orderId": "pp_order_10001",
        "partnerOrderId": "partner-order-10001",
        "customerReference": "customer-42",
        "iccid": "8900000000000000000",
        "packageId": "onyx-connect-japan-10gb-30d",
        "status": "ready",
        "installPayloadAvailable": true,
        "usage": {
          "dataMbTotal": 10240,
          "dataMbUsed": 2048,
          "dataMbRemaining": 8192,
          "usagePercent": 20,
          "status": "active"
        }
      }
    ]
  }
}

Get One Service

GET /v1/partner/esims/{iccid}

Use this endpoint when support or activation needs the current state for one service record.

Service states are:

  • allocated
  • ready
  • downloaded
  • installed
  • expired
  • failed

Get Usage

GET /v1/partner/esims/{iccid}/usage

Returns the latest usage snapshot for one service record.

{
  "data": {
    "usage": {
      "iccid": "8900000000000000000",
      "packageId": "onyx-connect-japan-10gb-30d",
      "dataMbTotal": 10240,
      "dataMbUsed": 2048,
      "dataMbRemaining": 8192,
      "usagePercent": 20,
      "status": "active",
      "observedAt": "2026-06-11T00:00:00.000Z"
    }
  }
}

Usage States

Current usage states are:

  • not_started
  • active
  • threshold
  • exhausted
  • expired
  • unknown

Use the usage state and observedAt timestamp together. Do not present usage as a guaranteed live meter.

Safe Handling

Treat activation material as sensitive. Do not place installation details, service identifiers, or usage payloads in public logs, screenshots, analytics tools, or unsecured support messages.

Errors

esim_not_found means the service identifier is invalid or unavailable to your partner account.

invalid_request means the service identifier format is invalid.