Suspend / Activate eSIM

Block (suspend) or restore (activate) network access for an eSIM.

eSIMfly packages only

This operation is only available for eSIMfly eSIMs, which expose subscriber-level network control. Calling it for any other provider returns UNSUPPORTED_PROVIDER.

Endpoint

POST /api/v1/business/esims/suspend

AI prompt — Suspend / Activate eSIM

Open raw .txt

Paste into ChatGPT, Claude, Cursor, Copilot or any coding agent to generate this part of your integration. Built-in recommendation: Audited operator action for eSIMfly eSIMs; track suspended state locally instead of re-querying.

Show prompt text (45 lines)

# eSIMfly Business API — Suspend / Activate eSIM (POST /esims/suspend) — prompt for AI coding assistants

TASK: implement blocking and restoring network access for an eSIM (eSIMfly-provided eSIMs only). This is
an operator ACTION triggered from our admin/support console or a fraud/non-payment workflow — never a
scheduled or repeated call.

COMMON RULES (apply to every eSIMfly request)
- Base URL: https://esimfly.net/api/v1/business
- Headers on every call: RT-AccessCode (esf_...), RT-RequestID (fresh UUID v4 per request; reuse -> 400 DUPLICATE_REQUEST),
  RT-Timestamp (ms since epoch; >5 min old -> 401 INVALID_TIMESTAMP),
  RT-Signature = UPPERCASE hex HMAC-SHA256(secretKey, timestamp + requestId + accessCode + rawBody).
  rawBody = "" for GET; for POST/PUT sign the exact body string you send, with Content-Type: application/json.
- Keep access code + secret key server-side in env vars. Never ship them to a browser or mobile app.
- Responses: { success: true, ... } or { success: false, error|message, code }. Branch on `success` and `code`.
- Rate limits are per API key, shown in the business dashboard (typically 100/minute, 1,000/hour, 10,000/day) -> RATE_LIMIT_EXCEEDED. Pace bulk work at <= 1 req/s.
- Read `currency` from responses (USD | IQD | EUR for enterprise). Never hard-code it. IQD amounts are integers.
- Package codes are opaque strings: store and send back verbatim, never parse or prefix them.
- Node.js/TypeScript: use the official SDK instead of raw HTTP — `npm install @esimfly/sdk`
  (https://github.com/eSimfly-Official/esimfly-sdk-nodejs); it implements these rules. Other languages: implement the contract below.
- Full multi-endpoint prompt: https://docs.esimfly.net/llm/esimfly-api-full-prompt.txt

ENDPOINT
  POST https://esimfly.net/api/v1/business/esims/suspend
  Body: { "iccid": "8948010010036785060", "action": "suspend" }     // or "activate"; esimId may replace iccid

RESPONSE 200
  suspend : { success: true, message: "eSIM suspended. Network access has been blocked.",   data: { iccid, action: "suspend",  esim_status: "Disconnected" } }
  activate: { success: true, message: "eSIM activated. Network access has been restored.", data: { iccid, action: "activate", esim_status: "Active" } }

ERRORS: 400 INVALID_ACTION; 400 MISSING_IDENTIFIER; 400 UNSUPPORTED_PROVIDER (not an eSIMfly eSIM — hide the action for those);
        404 ESIM_NOT_FOUND.

INTEGRATION PATTERN
1. Show the Suspend/Activate control only for eSIMs whose package came from the eSIMfly provider
   (packages whose `networks`/`countries` fields were populated in the catalogue sync are eSIMfly packages);
   for others, UNSUPPORTED_PROVIDER is expected — hide the button rather than handling the error.
2. Record every action in an audit log (who, when, why) and store our own `suspended_at` on the esims row;
   read that field for UI state instead of calling the API to "check" whether it is suspended.
3. Suspend does not cancel or refund; use POST /esims/cancel for refunds of unused eSIMs.
4. Idempotent in practice: suspending an already suspended eSIM is harmless; still guard double clicks locally.
5. Use a fresh RT-RequestID per attempt; on timeout retry once.

DELIVERABLE: setEsimNetworkAccess(iccid, action) in the shared client, the audited admin action, and
the local suspended_at bookkeeping.

Building the whole integration? Use the complete prompt for all endpoints instead of combining the per-endpoint ones.

Authentication

This endpoint requires HMAC authentication. See Authentication for details.

Request Headers

Header	Type	Required	Description
RT-AccessCode	String	Yes	Your API access code
RT-RequestID	String	Yes	Unique request ID (UUID v4)
RT-Timestamp	String	Yes	Request timestamp in milliseconds
RT-Signature	String	Yes	HMAC-SHA256 signature
Content-Type	String	Yes	Must be "application/json"

Request Body

Field	Type	Required	Description
action	String	Yes	`"suspend"` to block network access, or `"activate"` to restore it
iccid	String	Yes*	The ICCID of the eSIM
esimId	Integer	Yes*	The eSIM `id` (used if `iccid` is not provided)

* Provide either iccid or esimId.

Suspend:

{
  "iccid": "8948010010036785060",
  "action": "suspend"
}

Activate:

{
  "iccid": "8948010010036785060",
  "action": "activate"
}

Response

Success Response (200 OK)

Suspend:

{
  "success": true,
  "message": "eSIM suspended. Network access has been blocked.",
  "data": {
    "iccid": "8948010010036785060",
    "action": "suspend",
    "esim_status": "Disconnected"
  }
}

Activate:

{
  "success": true,
  "message": "eSIM activated. Network access has been restored.",
  "data": {
    "iccid": "8948010010036785060",
    "action": "activate",
    "esim_status": "Active"
  }
}

Response Fields

Field	Type	Description
success	Boolean	Whether the status change succeeded
message	String	Human-readable result
data.iccid	String	The affected eSIM ICCID
data.action	String	The action performed (`suspend` / `activate`)
data.esim_status	String	New eSIM status (`Disconnected` when suspended, `Active` when activated)

Error Responses

400 Bad Request

Invalid action:

{ "success": false, "message": "action must be \"suspend\" or \"activate\"", "code": "INVALID_ACTION" }

Missing identifier:

{ "success": false, "message": "Provide either iccid or esimId", "code": "MISSING_IDENTIFIER" }

Unsupported provider:

{ "success": false, "message": "Suspend/activate is only available for eSIMfly eSIMs", "code": "UNSUPPORTED_PROVIDER" }

404 Not Found

{ "success": false, "message": "eSIM not found", "code": "ESIM_NOT_FOUND" }

Example

const crypto = require('crypto');
const { v4: uuidv4 } = require('uuid');

async function setEsimNetwork(iccid, action) { // action: 'suspend' | 'activate'
  const accessCode = 'esf_your_access_code';
  const secretKey = 'sk_your_secret_key';

  const body = JSON.stringify({ iccid, action });
  const timestamp = Date.now().toString();
  const requestId = uuidv4();
  const signData = timestamp + requestId + accessCode + body;
  const signature = crypto.createHmac('sha256', secretKey)
    .update(signData)
    .digest('hex')
    .toUpperCase();

  const response = await fetch('https://esimfly.net/api/v1/business/esims/suspend', {
    method: 'POST',
    headers: {
      'RT-AccessCode': accessCode,
      'RT-RequestID': requestId,
      'RT-Timestamp': timestamp,
      'RT-Signature': signature,
      'Content-Type': 'application/json'
    },
    body
  });

  return response.json();
}

Notes

Suspend blocks the eSIM from connecting to any network; activate restores it. The change takes effect on the carrier network shortly after the call succeeds.
Suspending does not cancel the eSIM or refund anything — use Cancel eSIM for that.
An eSIM can be suspended and re-activated as many times as needed.

Endpoint​

Authentication​

Request Headers​

Request Body​

Response​

Success Response (200 OK)​

Response Fields​

Error Responses​

400 Bad Request​

404 Not Found​

Example​

Notes​