Seamless Partner API
Sell eSIMs powered by the Seamless platform from your travel app, fintech, publication, or MVNO. Catalog → quote → order → activate → top-up → refund, all behind one bearer key.
Get a key
Your Seamless contact issues a sandbox key (sk_test_…) when you start evaluating. Partners with a portal login create and rotate keys at partner.withseamless.com → Developers → API keys. A production key (sk_live_…) is issued once commercial terms are agreed.
Quickstart
Install the Node SDK, browse real plans, and issue a test eSIM with your sandbox key:
npm install @withseamless/node
import { Seamless } from "@withseamless/node";
const seamless = new Seamless({ apiKey: process.env.SEAMLESS_API_KEY! }); // sk_test_…
// Browse real plans and prices — works with a sandbox key.
const japan = await seamless.catalog.getCountry("japan");
console.log(`Japan: ${japan.package_count} plans from $${japan.starts_at_usd}`);
// A sandbox key orders the free Sandbox SKU; a live key orders any plan.
const { packages: [plan] } = await seamless.catalog.getCountry("sandbox");
let order = await seamless.orders.create({
lines: [{ package_detail_id: plan.package_detail_id }],
payment_mode: "partner_wallet",
customer: { email: "[email protected]" },
});
// eSIMs are issued asynchronously, usually within seconds.
// Poll as below, or listen for the order.provisioned webhook.
while (order.lines[0].sims[0].status === "pending") {
await new Promise((r) => setTimeout(r, 2000));
order = await seamless.orders.retrieve(order.id);
}
const sim = order.lines[0].sims[0];
const install = await seamless.esims.installLink(sim.iccid!);
console.log("Apple one-tap: ", install.apple_url);
console.log("Android one-tap:", install.android_url);No Node? Every call is plain HTTPS to https://api.withseamless.com/v1 with Authorization: Bearer sk_test_… — see the reference.
Concepts
- Sandbox.
sk_test_keys see the real catalogue and real prices, so you can build your storefront against live data. Orders and top-ups are limited to the free Sandbox SKU (GET /catalog/countries/sandbox), which issues a test eSIM — the full order → eSIM → install → top-up → refund flow runs without money. Sandbox has its own wallet with $100 of play money; reset it withPOST /sandbox/reset.sk_live_keys order real plans and debit your wallet. Same URL; the key prefix is the only switch. - Asynchronous provisioning.
POST /ordersreturns at once with each SIMpending; the ICCID and activation details appear onGET /orders/{id}and in theorder.provisionedwebhook. - Plans.
data_mbis binary (1 GB = 1024 MB).kindisfixed(data for the whole validity),daily(data_mbresets each day) orunlimited. - Idempotency.
Idempotency-Keyrequired on every mutating call. Same key + same body within 24h = cached replay. Same key + different body =409 idempotency_mismatch. The SDK auto-injects a UUID per call. - Price locks.
GET /pricing/quotereturns a 15-minute signedtoken. Pass it back asprice_quote_tokenon the order line to lock the price. - Webhooks. Stripe-format
Seamless-Signature: t=<unix>,v1=<hex>with a 5-minute replay window;Webhooks.constructEventin the SDK verifies and parses in one call. Events:order.created,order.paid,order.provisioned,order.failed,topup.applied,topup.failed,refund.succeeded,refund.failed,esim.usage_threshold,esim.expired,wallet.low_balance,wallet.topup_received. Register endpoints in the partner portal (Webhooks).
API reference
Full machine-readable contract at /reference (rendered from openapi.yaml).
Support
Email [email protected]. For commercial conversations (production approval, revenue share), [email protected].