{ "openapi": "3.1.0", "info": { "title": "goAFK Partner API", "version": "1.0.0", "summary": "Buy and manage eSIMs under your own brand.", "description": "Resell global eSIM data plans through your own product. You call goAFK, goAFK handles the carrier relationship, and your end users never see a third party.\n\nAccounts are opened by our team, not self-serve. Your account carries a pre-paid USD balance; every purchase debits it atomically before an eSIM is issued.", "contact": { "name": "goAFK partner support", "email": "support@goafk.io" } }, "servers": [ { "url": "https://goafk.io/api/v1", "description": "Production. This is the live base URL — use it today." } ], "tags": [ { "name": "Plans", "description": "Browse the catalogue at your own pricing." }, { "name": "eSIMs", "description": "Issue eSIMs, inspect them, and top them up." }, { "name": "Orders", "description": "Your billing history." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/plans": { "get": { "operationId": "listPlans", "summary": "List available plans", "tags": [ "Plans" ], "description": "Returns the full catalogue, priced at your markup. This endpoint is NOT paginated — narrow it with the filters below rather than fetching everything on each page load, and cache the result.", "parameters": [ { "name": "country", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 country code. Case-insensitive.", "schema": { "type": "string", "example": "FR" } }, { "name": "region", "in": "query", "required": false, "description": "Regional grouping, matched exactly and case-sensitively.", "schema": { "type": "string", "example": "Europe" } } ], "responses": { "200": { "description": "The catalogue.", "headers": { "X-Request-Id": { "description": "Unique id for this request. Present on every response, success or failure.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "This partner's requests-per-minute ceiling.", "schema": { "type": "integer", "example": 60 } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60-second window.", "schema": { "type": "integer", "example": 59 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "plans" ], "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } } } } } } }, "401": { "description": "Missing, malformed, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } }, "429": { "description": "Rate limit exceeded. Retry after the Retry-After interval.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } } } } }, "/plans/{id}": { "get": { "operationId": "getPlan", "summary": "Retrieve one plan", "tags": [ "Plans" ], "description": "Fetch a single plan by id, priced at your markup.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The plan id.", "schema": { "type": "string", "example": "156057" } } ], "responses": { "200": { "description": "The plan.", "headers": { "X-Request-Id": { "description": "Unique id for this request. Present on every response, success or failure.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "This partner's requests-per-minute ceiling.", "schema": { "type": "integer", "example": 60 } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60-second window.", "schema": { "type": "integer", "example": 59 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "plan" ], "properties": { "plan": { "$ref": "#/components/schemas/Plan" } } } } } }, "401": { "description": "Missing, malformed, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } }, "404": { "description": "No plan with that id.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } } }, "x-error-codes": [ "PLAN_NOT_FOUND" ] } }, "/esims": { "post": { "operationId": "purchaseEsim", "summary": "Buy an eSIM", "tags": [ "eSIMs" ], "description": "Debits your balance and issues an eSIM. The debit happens FIRST and is atomic: if it fails, nothing else runs. If the debit succeeds but the carrier then refuses, the charge is automatically reversed and the order is recorded as `provider_failed` — you are never charged for an eSIM you did not receive.\n\nAn `Idempotency-Key` header is REQUIRED. If a request times out, retry it with the SAME key: the reply is the original order, and no second charge is made.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "REQUIRED on every operation that spends money. Any string up to 200 characters; a UUID per logical purchase is the usual choice. Replaying a key returns the original order instead of charging again.", "schema": { "type": "string", "example": "3f8a1c2e-9b4d-4f77-8a10-2c5e7d9b1f34" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "plan_id" ], "properties": { "plan_id": { "type": "string", "description": "The id of the plan to buy, from GET /plans.", "example": "156057" } } } } } }, "responses": { "201": { "description": "The eSIM was issued and your balance was debited. On an idempotent replay the status is still 201, with `Idempotency-Replayed: true` set.", "headers": { "X-Request-Id": { "description": "Unique id for this request. Present on every response, success or failure.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "This partner's requests-per-minute ceiling.", "schema": { "type": "integer", "example": 60 } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60-second window.", "schema": { "type": "integer", "example": 59 } }, "Idempotency-Replayed": { "description": "Present and 'true' only when this response replays an earlier request rather than performing a new purchase.", "schema": { "type": "string", "example": "true" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "esim", "order" ], "properties": { "esim": { "$ref": "#/components/schemas/Esim" }, "order": { "$ref": "#/components/schemas/Order" } } } } } }, "400": { "description": "plan_id is missing, or the Idempotency-Key header is absent or over 200 characters.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } }, "401": { "description": "Missing, malformed, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } }, "402": { "description": "Your balance will not cover this plan. Nothing was charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } }, "404": { "description": "No plan with that id.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } }, "502": { "description": "The carrier refused. Your balance has already been refunded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } } }, "x-error-codes": [ "INVALID_REQUEST", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_TOO_LONG", "INSUFFICIENT_FUNDS", "PLAN_NOT_FOUND", "PROVIDER_ERROR" ] }, "get": { "operationId": "listEsims", "summary": "List your eSIMs", "tags": [ "eSIMs" ], "description": "Your own eSIMs only, newest first. Another partner's inventory is never visible.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "1-based page number. Values below 1 are clamped to 1.", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per page. Clamped to the 1–100 range.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "example": 50 } } ], "responses": { "200": { "description": "A page of eSIMs.", "headers": { "X-Request-Id": { "description": "Unique id for this request. Present on every response, success or failure.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "This partner's requests-per-minute ceiling.", "schema": { "type": "integer", "example": 60 } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60-second window.", "schema": { "type": "integer", "example": 59 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "esims", "total", "page", "limit" ], "properties": { "esims": { "type": "array", "items": { "$ref": "#/components/schemas/Esim" } }, "total": { "type": "integer", "description": "Total rows matching, across all pages.", "example": 128 }, "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 50 } } } } } }, "401": { "description": "Missing, malformed, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } } } } }, "/esims/{id}": { "get": { "operationId": "getEsim", "summary": "Retrieve one eSIM", "tags": [ "eSIMs" ], "description": "Returns cached fields, which is enough to render an installation screen. For live consumption use the usage endpoint instead.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The goAFK eSIM id (not the ICCID).", "schema": { "type": "string", "format": "uuid", "example": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6" } } ], "responses": { "200": { "description": "The eSIM.", "headers": { "X-Request-Id": { "description": "Unique id for this request. Present on every response, success or failure.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "This partner's requests-per-minute ceiling.", "schema": { "type": "integer", "example": 60 } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60-second window.", "schema": { "type": "integer", "example": 59 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "esim" ], "properties": { "esim": { "$ref": "#/components/schemas/Esim" } } } } } }, "401": { "description": "Missing, malformed, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } }, "404": { "description": "No such eSIM in YOUR account. An id belonging to another partner also returns 404.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } } }, "x-error-codes": [ "ESIM_NOT_FOUND" ] } }, "/esims/{id}/topup": { "post": { "operationId": "topUpEsim", "summary": "Top up an eSIM", "tags": [ "eSIMs" ], "description": "Adds another plan to an eSIM you already issued, keeping the same ICCID so the end user does not reinstall anything. Charging works exactly as it does for a purchase: atomic debit first, automatic refund if the carrier refuses, and an `Idempotency-Key` header is REQUIRED.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The goAFK eSIM id to top up.", "schema": { "type": "string", "format": "uuid", "example": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "REQUIRED on every operation that spends money. Any string up to 200 characters; a UUID per logical purchase is the usual choice. Replaying a key returns the original order instead of charging again.", "schema": { "type": "string", "example": "3f8a1c2e-9b4d-4f77-8a10-2c5e7d9b1f34" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "plan_id" ], "properties": { "plan_id": { "type": "string", "description": "The plan to add.", "example": "156057" } } } } } }, "responses": { "201": { "description": "The top-up was applied. `order` is null in the rare case the order row could not be re-read afterwards; the top-up itself still succeeded.", "headers": { "X-Request-Id": { "description": "Unique id for this request. Present on every response, success or failure.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "This partner's requests-per-minute ceiling.", "schema": { "type": "integer", "example": 60 } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60-second window.", "schema": { "type": "integer", "example": 59 } }, "Idempotency-Replayed": { "description": "Present and 'true' when this response replays an earlier request.", "schema": { "type": "string", "example": "true" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "esim", "order" ], "properties": { "esim": { "$ref": "#/components/schemas/Esim" }, "order": { "anyOf": [ { "$ref": "#/components/schemas/Order" }, { "type": "null" } ] } } } } } }, "400": { "description": "plan_id is missing, or the Idempotency-Key header is absent or over 200 characters.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } }, "401": { "description": "Missing, malformed, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } }, "402": { "description": "Your balance will not cover this plan. Nothing was charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } }, "404": { "description": "No such eSIM in your account, or no plan with that id.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } }, "502": { "description": "The carrier refused the top-up. Your balance has already been refunded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } } }, "x-error-codes": [ "INVALID_REQUEST", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_TOO_LONG", "INSUFFICIENT_FUNDS", "ESIM_NOT_FOUND", "PLAN_NOT_FOUND", "PROVIDER_ERROR" ] } }, "/esims/{id}/usage": { "get": { "operationId": "getEsimUsage", "summary": "Read live usage", "tags": [ "eSIMs" ], "description": "Queries the carrier directly, so this is the authoritative number — and it is slower than the other reads. Poll it on demand, not on a tight loop. The result also refreshes the cached fields on the eSIM.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The goAFK eSIM id.", "schema": { "type": "string", "format": "uuid", "example": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6" } } ], "responses": { "200": { "description": "Live usage.", "headers": { "X-Request-Id": { "description": "Unique id for this request. Present on every response, success or failure.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "This partner's requests-per-minute ceiling.", "schema": { "type": "integer", "example": 60 } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60-second window.", "schema": { "type": "integer", "example": 59 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "usage" ], "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "401": { "description": "Missing, malformed, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } }, "404": { "description": "No such eSIM in your account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } }, "502": { "description": "The carrier could not be reached. Retry; nothing was changed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } } }, "x-error-codes": [ "ESIM_NOT_FOUND", "PROVIDER_ERROR" ] } }, "/orders": { "get": { "operationId": "listOrders", "summary": "List your orders", "tags": [ "Orders" ], "description": "Every charge against your balance, newest first. This is the record to reconcile your own billing against.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "1-based page number. Values below 1 are clamped to 1.", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per page. Clamped to the 1–100 range.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "example": 50 } } ], "responses": { "200": { "description": "A page of orders.", "headers": { "X-Request-Id": { "description": "Unique id for this request. Present on every response, success or failure.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "This partner's requests-per-minute ceiling.", "schema": { "type": "integer", "example": 60 } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60-second window.", "schema": { "type": "integer", "example": 59 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "orders", "total", "page", "limit" ], "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "total": { "type": "integer", "example": 128 }, "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 50 } } } } } }, "401": { "description": "Missing, malformed, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } } } } }, "/orders/{id}": { "get": { "operationId": "getOrder", "summary": "Retrieve one order", "tags": [ "Orders" ], "description": "Fetch a single order from your own history.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The order id.", "schema": { "type": "string", "format": "uuid", "example": "2b7c9d1e-4f60-4a23-9c81-5d6e7f809a1b" } } ], "responses": { "200": { "description": "The order.", "headers": { "X-Request-Id": { "description": "Unique id for this request. Present on every response, success or failure.", "schema": { "type": "string", "format": "uuid" } }, "X-RateLimit-Limit": { "description": "This partner's requests-per-minute ceiling.", "schema": { "type": "integer", "example": 60 } }, "X-RateLimit-Remaining": { "description": "Requests left in the current 60-second window.", "schema": { "type": "integer", "example": 59 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "order" ], "properties": { "order": { "$ref": "#/components/schemas/Order" } } } } } }, "401": { "description": "Missing, malformed, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } }, "404": { "description": "No such order in your account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } } }, "x-error-codes": [ "ORDER_NOT_FOUND" ] } } }, "webhooks": { "esim.purchased": { "post": { "operationId": "webhookEsimPurchased", "summary": "An eSIM was issued", "tags": [ "Webhooks" ], "description": "Sent after a successful POST /esims. Carries the same `esim` and `order` objects the API call returned, so a receiver can provision on the webhook alone.", "responses": { "200": { "description": "Acknowledged. Any 2xx stops the retries." } } } }, "esim.topped_up": { "post": { "operationId": "webhookEsimToppedUp", "summary": "An eSIM received more data", "tags": [ "Webhooks" ], "description": "Sent after a successful top-up. Same shape as esim.purchased.", "responses": { "200": { "description": "Acknowledged." } } } }, "order.failed": { "post": { "operationId": "webhookOrderFailed", "summary": "An order was reversed", "tags": [ "Webhooks" ], "description": "Sent when we debited your balance, the carrier then refused, and the charge was automatically refunded. `refunded_cents` is what went back.", "responses": { "200": { "description": "Acknowledged." } } } }, "balance.low": { "post": { "operationId": "webhookBalanceLow", "summary": "Your balance crossed the alert threshold", "tags": [ "Webhooks" ], "description": "Sent once, on the purchase that takes your balance BELOW the threshold — not on every subsequent purchase while it stays low. An alert that repeats is an alert that gets ignored.", "responses": { "200": { "description": "Acknowledged." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Send your API key as `Authorization: Bearer gak_live_...`. Keys are issued by goAFK and shown exactly once — we store only a hash and cannot recover the key for you. Treat it as a password: server-side only, never in a browser or a mobile app." } }, "schemas": { "Plan": { "type": "object", "description": "A data plan, priced for the calling partner.", "required": [ "id", "country_code", "country_name", "region", "type", "data_gb", "duration_days", "price_usd_cents", "currency" ], "properties": { "id": { "type": "string", "description": "Pass this as plan_id when buying.", "example": "156057" }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2, upper case.", "example": "FR" }, "country_name": { "type": "string", "description": "English country name.", "example": "France" }, "region": { "type": [ "string", "null" ], "description": "Regional grouping, or null for a single-country plan.", "example": "Europe" }, "type": { "type": "string", "enum": [ "fixed", "unlimited" ], "description": "'fixed' has a data cap; 'unlimited' does not, and reports data_gb as null.", "example": "fixed" }, "data_gb": { "type": [ "number", "null" ], "description": "Included data in GB. Null for unlimited plans.", "example": 5 }, "duration_days": { "type": "integer", "description": "Validity from activation.", "example": 30 }, "price_usd_cents": { "type": "integer", "description": "What YOUR account is charged, in integer cents — wholesale plus your contracted markup. Two partners can legitimately see different prices for the same plan.", "example": 1595 }, "currency": { "type": "string", "enum": [ "USD" ], "description": "Always USD.", "example": "USD" } } }, "Esim": { "type": "object", "description": "An eSIM issued to the calling partner.", "required": [ "id", "iccid", "activation_code", "qr_code_url", "status", "data_total_mb", "data_used_mb", "expires_at", "plan_id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "goAFK identifier. Use this in URLs.", "example": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6" }, "iccid": { "type": "string", "description": "The SIM serial number.", "example": "8944478000001234567" }, "activation_code": { "type": "string", "description": "The LPA string to install the profile. Hand it to the end user verbatim, or encode it as a QR code yourself.", "example": "LPA:1$smdp.example.com$QR-G-5C-1LO-1S9L3JT" }, "qr_code_url": { "type": [ "string", "null" ], "description": "Ready-made QR image, when the provider supplies one.", "example": "https://cdn.example.com/qr/8944478000001234567.png" }, "status": { "type": "string", "enum": [ "inactive", "active", "expired", "depleted" ], "description": "Starts 'inactive' and becomes 'active' on first use. This field is a cached copy; call the usage endpoint for the live value.", "example": "inactive" }, "data_total_mb": { "type": "integer", "description": "Total data allowance in MB.", "example": 5120 }, "data_used_mb": { "type": "integer", "description": "Cached consumption in MB.", "example": 0 }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Null until the plan is activated.", "example": null }, "plan_id": { "type": "string", "description": "The plan this eSIM was issued from.", "example": "156057" } } }, "Order": { "type": "object", "description": "One movement against your balance.", "required": [ "id", "kind", "price_usd_cents", "currency", "plan_id", "partner_esim_id", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "2b7c9d1e-4f60-4a23-9c81-5d6e7f809a1b" }, "kind": { "type": "string", "enum": [ "purchase", "topup" ], "description": "'purchase' issued a new eSIM; 'topup' added data to an existing one.", "example": "purchase" }, "price_usd_cents": { "type": "integer", "description": "What you were charged, in integer cents.", "example": 1595 }, "currency": { "type": "string", "enum": [ "USD" ], "example": "USD" }, "plan_id": { "type": "string", "example": "156057" }, "partner_esim_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The eSIM this order produced or topped up. Null if provisioning failed.", "example": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6" }, "status": { "type": "string", "enum": [ "completed", "provider_failed", "refunded" ], "description": "'provider_failed' means you were charged, the provider refused, and the money was automatically returned to your balance. The row is kept as an audit trail.", "example": "completed" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-17T09:24:11.482Z" } } }, "Usage": { "type": "object", "description": "Live consumption, read from the network at request time.", "required": [ "iccid", "data_used_mb", "data_total_mb", "status", "expires_at" ], "properties": { "iccid": { "type": "string", "example": "8944478000001234567" }, "data_used_mb": { "type": "integer", "example": 812 }, "data_total_mb": { "type": "integer", "example": 5120 }, "status": { "type": "string", "enum": [ "inactive", "active", "expired", "depleted" ], "example": "active" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-09-16T09:24:11.482Z" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code. Branch on this, not on the message.", "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; do not parse it.", "example": "Partner balance is insufficient for plan price 4.50 USD" }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this in a support ticket. Also returned as the X-Request-Id header.", "example": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b" } } } } } } } }