Seamless docs

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 with POST /sandbox/reset. sk_live_ keys order real plans and debit your wallet. Same URL; the key prefix is the only switch.
  • Asynchronous provisioning. POST /orders returns at once with each SIM pending; the ICCID and activation details appear on GET /orders/{id} and in the order.provisioned webhook.
  • Plans. data_mb is binary (1 GB = 1024 MB). kind is fixed (data for the whole validity), daily (data_mb resets each day) or unlimited.
  • Idempotency. Idempotency-Key required 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/quote returns a 15-minute signed token. Pass it back as price_quote_token on the order line to lock the price.
  • Webhooks. Stripe-format Seamless-Signature: t=<unix>,v1=<hex> with a 5-minute replay window; Webhooks.constructEvent in 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].