API docs by Redocly

eSIM Commerce Production API (1.0)

Download OpenAPI specification:

Production API for eSIM Commerce service

eSIM

Get available data plans

Returns a paginated list of data plans available for the reseller. Optionally filter by country code (ISO 3166-1 alpha-2, 2 uppercase letters) and provider code.

Authorizations:
(X-API-Key-IDX-API-Key-Secret)
query Parameters
countryCode
string
Example: countryCode=JP

Country code to filter (ISO 3166-1 alpha-2, 2 uppercase letters)

providerCode
string
Example: providerCode=KDDI

Provider code to filter by

page
number
Example: page=1

Page number (1-based)

limit
number
Example: limit=200

Items per page (1-200)

includeRoaming
boolean
Example: includeRoaming=false

Include roaming countries in search. When true, searches both homeCountry and roamingCountries. When false (default), searches homeCountry only.

Responses

Response Schema: application/json
required
Array of objects (DataPlanResponseDto)

List of data plans

required
object

Pagination metadata

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "meta": {
    }
}

eSIM order

Requests new eSIM order for the reseller. The quantity parameter specifies the number of eSIMs to order (1-1000). Different ICCIDs are allocated per request. Rate limit: 10 requests per minute.

Authorizations:
(X-API-Key-IDX-API-Key-Secret)
Request Body schema: application/json
required
planCode
required
string

Plan code

quantity
required
integer [ 1 .. 1000 ]

Number of eSIMs to order (1-1000)

Responses

Request samples

Content type
application/json
{
  • "planCode": "RB52",
  • "quantity": 1
}

Response samples

Content type
application/json
{
  • "transactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "esims": [
    ]
}

eSIM status inquiry

Queries the current state of a specified eSIM (ICCID) from the MNO core system, returning the latest contract and profile-download information. Under core-system load, the latest data may be temporarily unavailable; in such cases, cached data is returned. If the server returns Retry-After, honor that value for re-queries. Rate limit: 60 requests per minute.

Authorizations:
(X-API-Key-IDX-API-Key-Secret)
path Parameters
iccid
required
string
Example: 8981100000000000001

ICCID (19-digit numeric string: 18-digit base + 1-digit check digit)

Responses

Response Headers
X-RateLimit-Limit
integer
Example: "60"

Maximum number of requests allowed per minute

X-RateLimit-Remaining
integer
Example: "59"

Number of requests remaining in the current time window

X-RateLimit-Reset
integer
Example: "45"

Seconds until the rate limit resets

Response Schema: application/json
iccid
required
string

Unique identifier for this eSIM (ICCID). Use this value to query eSIM status or perform operations like emergency control.

homeCountry
required
string

Home country where this eSIM is primarily used (ISO 3166-1 alpha-2 code, e.g., JP for Japan, US for United States).

roamingCountries
required
Array of strings

List of roaming countries where this eSIM can also be used (ISO 3166-1 alpha-2 codes). Empty array if no roaming is available.

contractStatus
required
string
Enum: "ACTIVE" "SUSPENDED" "TERMINATED"

Current contract status. ACTIVE: eSIM is usable. SUSPENDED: Temporarily suspended via emergency control (can be released). TERMINATED: Service ended permanently (expired or canceled).

profileProvisionStatus
required
string
Enum: "RESERVATION_PENDING" "RESERVED" "FINALIZED" "AVAILABLE" "DOWNLOADED" "CANCELED" "ERROR"

eSIM profile provision status. AVAILABLE: Ready for user to download. DOWNLOADED: User has downloaded the profile. CANCELED/ERROR: Profile is no longer available.

profileInstallStatus
required
string
Enum: "READY" "CONFIRMATION_FAILED" "DOWNLOADED" "INSTALLED"

eSIM installation status on user device. READY: Not yet installed. DOWNLOADED: Profile downloaded to device. INSTALLED: Successfully installed and ready to use.

isServiceRestricted
required
boolean

Whether network access is currently blocked. True when emergency control (suspend) is active. Use emergency control API to release the restriction.

qrCode
required
string

QR code content for eSIM installation. Generate a QR code from this string and let the end user scan it with their device to install the eSIM profile.

smdpAddress
required
string

SM-DP+ server address for manual eSIM setup. Provide this to end users who cannot scan QR codes and need to enter details manually.

activationCode
required
string

Activation code for manual eSIM setup. Used together with smdpAddress when end users enter eSIM details manually instead of scanning QR code.

activationDeadline
required
string or null

Deadline for eSIM installation (ISO 8601 UTC). The end user must install the eSIM before this date. Null if no deadline is set.

downloadedAt
required
string or null

When the end user downloaded the eSIM profile to their device (ISO 8601 UTC). Null if not yet downloaded. This indicates the user has received the profile but may not have installed it yet.

activatedOn
required
string or null <date>

Date when the eSIM was first activated by connecting to the network (YYYY-MM-DD, Japan time). Null if never activated. This marks the start of the service period for time-limited plans.

terminatedOn
required
string or null <date>

Date when the eSIM service was terminated (YYYY-MM-DD, Japan time). This is the line termination date from the provider, not an expiration date. Null if not yet terminated.

expiresOn
required
string or null <date>

Plan expiration date in Japan Standard Time (YYYY-MM-DD). The service will be terminated at an unspecified time on the following day. Null if not yet activated.

initialInsertionDevice
required
string or null

IMEI of the device where eSIM was first installed (15-digit). Null if not yet installed. Useful for tracking which device the end user is using.

initialInsertionAt
required
string or null

When the eSIM was first installed on a device (ISO 8601 UTC). Null if not yet installed.

initialConnectionDevice
required
string or null

IMEI of the device that first connected to the network (15-digit). Null if never connected. May differ from initialInsertionDevice if user moved eSIM to another device.

required
Array of objects (DataUsageDailyItemDto)

Daily data usage breakdown. Each entry contains the date and kilobytes (KB) used on that day. Empty array if no usage data is available yet.

totalDataUsage
required
integer

Total cumulative data usage for this eSIM, in kilobytes (KB).

lastUpdatedAt
required
string

When this eSIM data was last synced from the carrier (ISO 8601 UTC). Data may be slightly delayed. For real-time status, call the eSIM status API again.

Response samples

Content type
application/json
{
  • "iccid": "8981100000000000001",
  • "homeCountry": "JP",
  • "roamingCountries": [
    ],
  • "contractStatus": "ACTIVE",
  • "profileProvisionStatus": "AVAILABLE",
  • "profileInstallStatus": "READY",
  • "isServiceRestricted": false,
  • "qrCode": "LPA:1$smdp.example.com$CODE123",
  • "smdpAddress": "smdp.example.com",
  • "activationCode": "CODE123",
  • "activationDeadline": "2026-06-05T00:00:00.000Z",
  • "downloadedAt": "2025-07-15T00:46:09.816Z",
  • "activatedOn": "2025-12-01",
  • "terminatedOn": "2025-12-31",
  • "expiresOn": "2025-12-07",
  • "initialInsertionDevice": "123456789012345",
  • "initialInsertionAt": "2025-12-01T10:00:00.000Z",
  • "initialConnectionDevice": "123456789012345",
  • "dataUsageDailyList": [
    ],
  • "totalDataUsage": 307200,
  • "lastUpdatedAt": "2026-01-22T10:30:00.000Z"
}

Transaction inquiry

Returns the list of ICCIDs associated with the given transactionId. Use the transactionId returned from the Order eSIM API response. Intended for emergency reconciliation when the normal response could not be retrieved. Only orders received within 48 hours (JST) are eligible. If the specified transactionId does not exist, returns error code 400. Rate limit: 10 requests per minute.

Authorizations:
(X-API-Key-IDX-API-Key-Secret)
path Parameters
id
required
string
Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Transaction ID returned from Order eSIM API (valid for 48 hours from order receipt)

Responses

Response Headers
X-RateLimit-Limit
integer
Example: "60"

Maximum number of requests allowed per minute

X-RateLimit-Remaining
integer
Example: "59"

Number of requests remaining in the current time window

X-RateLimit-Reset
integer
Example: "45"

Seconds until the rate limit resets

Response Schema: application/json
transactionId
required
string

Transaction ID (UUID format)

iccids
required
Array of strings

List of allocated ICCIDs

Response samples

Content type
application/json
{
  • "transactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "iccids": [
    ]
}

Emergency control (suspend/release)

Requests emergency suspension or release of an eSIM. Use 'suspend' to suspend the eSIM, or 'release' to lift the suspension. The contract status (cmconMdlsts) will be updated to '03' (Suspended) or '01' (Active) accordingly. Rate limit: 10 requests per minute.

Authorizations:
(X-API-Key-IDX-API-Key-Secret)
path Parameters
iccid
required
string
Example: 8981100000000000001

ICCID (19-digit numeric string: 18-digit base + 1-digit check digit)

Request Body schema: application/json
required
action
required
string
Enum: "suspend" "release"

Action type: 'suspend' for emergency suspension, 'release' to lift the suspension

Responses

Request samples

Content type
application/json
{
  • "action": "suspend"
}

Response samples

Content type
application/json
{
  • "iccid": "8981100000000000001",
  • "homeCountry": "JP",
  • "roamingCountries": [
    ],
  • "contractStatus": "ACTIVE",
  • "profileProvisionStatus": "AVAILABLE",
  • "profileInstallStatus": "READY",
  • "isServiceRestricted": false,
  • "qrCode": "LPA:1$smdp.example.com$CODE123",
  • "smdpAddress": "smdp.example.com",
  • "activationCode": "CODE123",
  • "activationDeadline": "2026-06-05T00:00:00.000Z",
  • "downloadedAt": "2025-07-15T00:46:09.816Z",
  • "activatedOn": "2025-12-01",
  • "terminatedOn": "2025-12-31",
  • "expiresOn": "2025-12-07",
  • "initialInsertionDevice": "123456789012345",
  • "initialInsertionAt": "2025-12-01T10:00:00.000Z",
  • "initialConnectionDevice": "123456789012345",
  • "dataUsageDailyList": [
    ],
  • "totalDataUsage": 307200,
  • "lastUpdatedAt": "2026-01-22T10:30:00.000Z"
}