Simology API & SDK: Quick Start for Catalog, Checkout & Activation Webhooks

What Is the Simology API and Who Is It For?

The Simology API is a RESTful interface that gives developers, travel platforms, and OTA (online travel agency) partners direct programmatic access to Simology's global eSIM catalog, checkout pipeline, and post-purchase activation events. If you're building a travel app, a corporate travel management tool, or an e-commerce store that sells connectivity alongside flights and hotels, this API is your fastest path to offering instant eSIM delivery at scale.

According to the GSMA, the number of eSIM-capable consumer devices surpassed 2 billion globally in 2025 — a figure that's expected to grow to over 3.5 billion by 2028. That's a massive and rapidly expanding market for any platform that can offer embedded connectivity at the point of travel purchase. Meanwhile, Juniper Research estimates that eSIM connections will account for more than 50% of all mobile connections by 2027, underscoring why embedding eSIM sales into your product is no longer optional for travel-tech companies.

Quotable stat: "eSIM connections will exceed 3.5 billion by 2028, driven largely by international travel and IoT adoption." — GSMA Intelligence, 2025

Whether you're serving travelers heading to a Japan eSIM destination or building a regional platform for Southeast Asia connectivity, the Simology API abstracts away the complexity of carrier provisioning and gives you a clean, well-documented interface to work with.

---

What Do You Need Before You Start?

Before making your first API call, you need three things: an API key, a base URL, and a clear understanding of your authentication method. Setup takes under five minutes for most developers.

Getting Your API Credentials

1. Sign up for a Simology Partner Account at simology.io/partners. Partner accounts are available to businesses with a valid use case — travel apps, OTAs, corporate travel platforms, and developer tools all qualify.
2. Generate your API key from the Partner Dashboard under Settings → API Access. You'll receive a Bearer token used in every request header.
3. Note your environment URLs:
   • Sandbox: https://sandbox-api.simology.io/v2
   • Production: https://api.simology.io/v2

Always develop against the sandbox environment first. The sandbox mirrors production data but uses test payment tokens and does not provision real eSIMs.

Authentication

Every request must include an Authorization header:

Authorization: Bearer YOUR_API_KEY_HERE
Content-Type: application/json

Simology uses standard Bearer token authentication over HTTPS. Tokens do not expire automatically but can be rotated from the dashboard at any time. If a token is compromised, revoke it immediately from Settings → API Access → Revoke Token.

---

How Does the Catalog Endpoint Work?

The /catalog endpoint returns the full list of available eSIM plans for a given country or region, including pricing, data allowances, validity periods, and network coverage metadata. It's the starting point for any product display or recommendation feature you're building.

Basic Catalog Request

GET https://api.simology.io/v2/catalog?country=JP
Authorization: Bearer YOUR_API_KEY_HERE

Query Parameters:

Parameter	Type	Required	Description
country	string (ISO 3166-1 alpha-2)	Yes*	Two-letter country code (e.g. JP, AU, DE)
region	string	Yes*	Region slug (e.g. europe, asia, caribbean)
currency	string (ISO 4217)	No	Response currency. Defaults to USD
lang	string	No	Response language. Defaults to en

*Either country or region is required. You can pass both to filter regional plans that include a specific country.

Sample Catalog Response

{
  "status": "success",
  "country": "JP",
  "plans": [
    {
      "plan_id": "sim_jp_1gb_7d",
      "name": "Japan 1 GB – 7 Days",
      "data_gb": 1,
      "validity_days": 7,
      "price_usd": 4.90,
      "network_generation": "4G/5G",
      "coverage": ["JP"],
      "activation_type": "qr_code",
      "auto_install": false
    },
    {
      "plan_id": "sim_jp_5gb_30d",
      "name": "Japan 5 GB – 30 Days",
      "data_gb": 5,
      "validity_days": 30,
      "price_usd": 14.90,
      "network_generation": "4G/5G",
      "coverage": ["JP"],
      "activation_type": "qr_code",
      "auto_install": false
    }
  ]
}

Regional Plans vs. Country-Specific Plans

The Simology catalog includes both country-specific plans and multi-country regional plans. Regional plans are particularly popular for travelers visiting multiple destinations — for example, a single Europe plan covering 40+ countries, or a Caribbean eSIM plan covering popular island destinations.

To retrieve regional plans:

GET https://api.simology.io/v2/catalog?region=europe&currency=EUR

Regional plan objects include an expanded coverage array listing every country the plan is valid in. You can use this to build smart recommendation logic: if a user adds flights to both France and Germany, surface a regional European plan rather than two separate country plans.

---

How Does the Checkout Endpoint Work?

The /checkout endpoint creates an eSIM order. It accepts a plan_id, a customer email, and an optional set of metadata fields, then returns an order_id and — if the plan supports instant provisioning — a QR code payload or installation URL.

Creating an Order

POST https://api.simology.io/v2/checkout
Authorization: Bearer YOUR_API_KEY_HERE
Content-Type: application/json

{
  "plan_id": "sim_jp_5gb_30d",
  "customer_email": "traveler@example.com",
  "currency": "USD",
  "metadata": {
    "partner_order_id": "ORD-98765",
    "traveler_name": "Alex Johnson"
  }
}

Checkout Response Object

{
  "status": "success",
  "order_id": "sml_ord_a1b2c3d4e5",
  "plan_id": "sim_jp_5gb_30d",
  "customer_email": "traveler@example.com",
  "price_usd": 14.90,
  "currency_charged": "USD",
  "esim": {
    "iccid": "89882280000012345678",
    "activation_code": "LPA:1$rsp.simology.io$ABCDE12345",
    "qr_code_url": "https://api.simology.io/v2/qr/sml_ord_a1b2c3d4e5.png",
    "manual_install_url": "https://simology.io/activate/ABCDE12345"
  },
  "status_url": "https://api.simology.io/v2/orders/sml_ord_a1b2c3d4e5",
  "created_at": "2026-07-18T10:22:00Z"
}

What Happens After Checkout?

Once an order is created successfully, Simology's provisioning system immediately requests the eSIM profile from the relevant carrier infrastructure. The ICCID and activation code are generated within seconds for most plans. The qr_code_url points to a hosted PNG image you can display directly in your app or email to the customer.

The manual_install_url is a fallback for users who prefer step-by-step guided installation — particularly useful for travelers who are less tech-savvy or are installing the eSIM on a device that doesn't support camera-based QR scanning.

Handling Payment in Your Integration

The Simology API does not process payment directly — it assumes your platform handles the payment flow (Stripe, Braintree, PayPal, etc.) before calling /checkout. Your API key is associated with a prepaid credit balance or a monthly invoiced account, depending on your partner agreement. Each successful /checkout call deducts the plan cost from your balance.

To check your current balance:

GET https://api.simology.io/v2/account/balance
Authorization: Bearer YOUR_API_KEY_HERE

---

How Do Activation Webhooks Work?

Activation webhooks are HTTP POST callbacks that Simology sends to your registered endpoint whenever an eSIM's status changes — for example, when a traveler installs the profile, when the plan becomes active, or when data usage crosses a threshold. They're the real-time nervous system of your integration.

Registering a Webhook Endpoint

Register your webhook URL from the Partner Dashboard under Settings → Webhooks → Add Endpoint, or via the API:

POST https://api.simology.io/v2/webhooks
Authorization: Bearer YOUR_API_KEY_HERE
Content-Type: application/json

{
  "url": "https://yourapp.com/webhooks/simology",
  "events": [
    "esim.installed",
    "esim.activated",
    "esim.data_low",
    "esim.expired",
    "order.failed"
  ],
  "secret": "your_webhook_signing_secret"
}

Webhook Event Types

Event	Trigger
esim.installed	Customer has scanned the QR code and installed the eSIM profile on their device
esim.activated	eSIM has connected to a network for the first time — plan validity clock starts
esim.data_low	Data usage has reached 80% of the plan allowance
esim.data_exhausted	All data has been consumed
esim.expired	Plan validity period has ended
order.failed	Provisioning failed (rare; see error codes)
order.refunded	Order has been refunded via the dashboard or API

Sample Webhook Payload

{
  "event": "esim.activated",
  "timestamp": "2026-07-18T14:05:33Z",
  "order_id": "sml_ord_a1b2c3d4e5",
  "iccid": "89882280000012345678",
  "plan_id": "sim_jp_5gb_30d",
  "data": {
    "data_used_mb": 12,
    "data_remaining_mb": 5108,
    "activated_at": "2026-07-18T14:05:33Z",
    "expires_at": "2026-08-17T14:05:33Z",
    "network": "major local networks"
  },
  "metadata": {
    "partner_order_id": "ORD-98765"
  }
}

Verifying Webhook Signatures

Every webhook request includes an X-Simology-Signature header — an HMAC-SHA256 hash of the raw request body, signed with your webhook secret. Always verify this signature before processing any webhook payload to prevent spoofed requests.

import hmac
import hashlib

def verify_signature(payload_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)

Return a 200 OK response immediately upon receipt — even before processing — to acknowledge delivery. If Simology doesn't receive a 2xx within 10 seconds, it will retry with exponential backoff (5s, 30s, 5min, 30min, 2h).

---

What Are the Most Common Integration Patterns?

Most Simology API integrations follow one of three patterns, depending on the platform type. Choosing the right pattern upfront saves significant rework later.

Pattern 1: Embedded Storefront (Travel Apps & OTAs)

This is the most common pattern. Your app displays a list of eSIM plans fetched from /catalog, the user selects a plan, your platform charges the customer, and you call /checkout to provision the eSIM. The QR code is displayed in-app or emailed immediately.

Best for: Flight booking apps, hotel platforms, travel insurance tools, itinerary planners.

Key considerations:

• Cache catalog responses for 15–30 minutes to reduce API calls. Plan prices and availability change infrequently.
• Use the metadata.partner_order_id field to correlate Simology orders with your own order management system.
• Listen to esim.activated webhooks to trigger post-purchase flows (e.g., send a "You're now connected in Japan!" push notification).

Pattern 2: White-Label Reseller

You sell Simology eSIMs under your own brand, with your own pricing markup. The API is the same, but you'll typically build a more complete customer-facing UI including order history, data usage dashboards, and support ticket integrations.

Best for: MVNOs, corporate travel management companies, telecom resellers.

Key considerations:

• Use the /orders/{order_id} GET endpoint to poll current eSIM status for customer dashboards.
• Implement esim.data_low webhooks to proactively upsell top-up plans before the customer runs out of data mid-trip.
• Consider building a North America eSIM or Western Europe eSIM bundle as a flagship product — these are the two highest-demand regional categories.

Pattern 3: Automated B2B Distribution

Corporate travel platforms and travel management companies (TMCs) often need to provision eSIMs automatically at booking time, without any manual customer action. In this pattern, the eSIM is provisioned at checkout and the QR code is included in the traveler's trip briefing document automatically.

Best for: Corporate travel management, event management companies, group travel operators.

Key considerations:

• Use the customer_email field to route the activation QR directly to the traveler's inbox via your own transactional email system.
• Batch orders are supported via the /checkout/batch endpoint (up to 50 orders per request).
• Ensure your webhook handler is idempotent — in rare cases, Simology may deliver the same event more than once.

---

What Are the Rate Limits and Error Codes?

Understanding rate limits and error handling before you go to production is critical. Hitting a rate limit in a live booking flow is a poor user experience that's entirely preventable.

Rate Limits

Endpoint	Sandbox Limit	Production Limit
GET /catalog	100 req/min	500 req/min
POST /checkout	20 req/min	200 req/min
POST /checkout/batch	5 req/min	50 req/min
GET /orders/{id}	60 req/min	300 req/min
POST /webhooks	10 req/min	10 req/min

Rate limit headers are returned on every response:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1752845220

Common Error Codes

HTTP Status	Error Code	Meaning
400	INVALID_PLAN_ID	The plan_id does not exist or is not available
400	INVALID_COUNTRY	Country code not recognized
401	UNAUTHORIZED	Missing or invalid API key
402	INSUFFICIENT_BALANCE	Partner account balance too low to complete order
404	ORDER_NOT_FOUND	The order_id does not exist in your account
409	DUPLICATE_ORDER	A partner_order_id with this value already exists
429	RATE_LIMIT_EXCEEDED	Too many requests — back off and retry
503	PROVISIONING_UNAVAILABLE	Temporary carrier provisioning issue — retry after 60s

For 503 errors specifically, implement an automatic retry with a 60-second delay. These are almost always transient carrier-side events that resolve within a minute or two.

---

How Do You Test Your Integration End-to-End?

Testing thoroughly in the sandbox environment before going live prevents the most common integration bugs. The sandbox supports the full API surface, including webhook delivery to your test endpoint.

Step-by-Step Sandbox Test Flow

1. Fetch the catalog for a test country (use country=AU for Australia — it has a broad range of test plans):

   GET https://sandbox-api.simology.io/v2/catalog?country=AU
   

2. Create a test order using any plan ID from the catalog response. Use a test email address.

3. Verify the response contains a valid iccid, activation_code, and qr_code_url.

4. Simulate webhook events by calling the sandbox trigger endpoint:

   POST https://sandbox-api.simology.io/v2/sandbox/trigger-event
   {
     "order_id": "YOUR_TEST_ORDER_ID",
     "event": "esim.activated"
   }
   

5. Confirm your webhook handler receives the event, verifies the signature, and responds with 200 OK.

6. Test error paths — try an invalid plan_id, an insufficient balance scenario, and a duplicate partner_order_id to ensure your error handling works correctly.

Using ngrok for Local Webhook Testing

If you're developing locally, use ngrok or a similar tunneling tool to expose your local server to the internet for webhook delivery:

ngrok http 3000
# Simology webhook URL: https://abc123.ngrok.io/webhooks/simology

Register the ngrok URL as your webhook endpoint in the sandbox dashboard. Remember to update it each time you restart ngrok unless you're using a static domain (available on ngrok's paid plans).

---

What SDK Options Are Available?

In addition to the raw REST API, Simology provides official SDKs for the most common server-side languages. SDKs handle authentication, request serialization, response parsing, and webhook signature verification out of the box.

Official SDK Languages (2026)

Language	Package	Install
Node.js / TypeScript	@simology/sdk	npm install @simology/sdk
Python	simology-sdk	pip install simology-sdk
PHP	simology/simology-php	composer require simology/simology-php
Ruby	simology-ruby	gem install simology-ruby
Go	github.com/simology-io/go-sdk	go get github.com/simology-io/go-sdk

Node.js Quick Start Example

import { SimologyClient } from '@simology/sdk';

const client = new SimologyClient({ apiKey: process.env.SIMOLOGY_API_KEY });

// Fetch catalog
const catalog = await client.catalog.list({ country: 'JP' });
console.log(catalog.plans);

// Create order
const order = await client.checkout.create({
  planId: 'sim_jp_5gb_30d',
  customerEmail: 'traveler@example.com',
  metadata: { partnerOrderId: 'ORD-98765' }
});

console.log(order.esim.qrCodeUrl);

// Handle webhook (Express example)
app.post('/webhooks/simology', client.webhooks.express(async (event) => {
  if (event.type === 'esim.activated') {
    await notifyTraveler(event.orderId);
  }
}));

The SDK's webhooks.express() helper automatically verifies signatures and parses payloads — you don't need to implement HMAC verification manually.

---

FAQ

How do I get access to the Simology API?

Sign up for a Simology Partner Account at simology.io/partners and generate an API key from the Partner Dashboard. Sandbox access is available immediately upon registration. Production access requires a brief review of your use case, which typically completes within one business day.

Can I use the Simology API to sell eSIMs for any country?

Yes — the Simology catalog covers 190+ countries and territories, from high-demand destinations like Japan and Australia to regional multi-country plans. You can query available plans by country code or by region slug. Not all countries have the same range of plans; use the /catalog endpoint to check current availability for your target markets.

What happens if a webhook delivery fails?

If your endpoint doesn't return a 2xx response within 10 seconds, Simology retries with exponential backoff: after 5 seconds, 30 seconds, 5 minutes, 30 minutes, and finally 2 hours. If all retries fail, the event is marked as undelivered and you can manually re-trigger it from the Partner Dashboard under Webhooks → Failed Events. Always make your webhook handler idempotent to handle potential duplicate deliveries gracefully.

Is there a test environment I can use before going live?

Yes — the sandbox environment at https://sandbox-api.simology.io/v2 mirrors the full production API surface without provisioning real eSIMs or charging real money. You can also trigger simulated webhook events using the POST /sandbox/trigger-event endpoint to test your event handling logic end-to-end without waiting for real traveler activity.

How does billing work for API partners?

Simology API partners are billed either on a prepaid credit basis or via monthly invoicing, depending on your partner agreement. Each successful /checkout call deducts the wholesale plan cost from your balance. You set your own retail markup. Check your current balance at any time via GET /account/balance. Low-balance alerts can be configured in the Partner Dashboard.

What is the difference between esim.installed and esim.activated?

esim.installed fires when the traveler scans the QR code and downloads the eSIM profile to their device — but the plan hasn't started yet. esim.activated fires when the device connects to a network for the first time, which is when the validity countdown begins. For most billing and notification use cases, esim.activated is the event you want to act on.

Can I offer top-up plans via the API if a traveler runs out of data?

Yes — the catalog includes top-up and add-on plans for supported destinations. Filter for plans with "plan_type": "topup" in the catalog response and associate them with the original order's iccid. The esim.data_low webhook (triggered at 80% data usage) is the ideal trigger for proactively surfacing top-up options to travelers before they run out.

Does the SDK handle rate limiting automatically?

The official Simology SDKs include built-in retry logic with exponential backoff for 429 Rate Limit Exceeded responses. You can configure the maximum retry count and backoff multiplier in the SDK client options. For the raw REST API, you'll need to implement your own retry logic by reading the X-RateLimit-Reset header to determine when the rate limit window resets.

---

Wrapping Up: From First API Call to Production

The Simology API is designed to get you from zero to a working eSIM integration in a single afternoon. The three-endpoint core — Catalog, Checkout, and Activation Webhooks — covers the full traveler journey: discovering a plan, purchasing it, and tracking it through activation and data consumption.

Here's the quick-reference checklist for going live:

• ✅ Partner account created and API key generated
• ✅ Catalog endpoint integrated with appropriate caching (15–30 min TTL)
• ✅ Checkout endpoint tested with sandbox orders for all plan types you'll offer
• ✅ Webhook endpoint registered, signature verification implemented, and idempotency handled
• ✅ Error handling covers 400, 402, 429, and 503 status codes
• ✅ End-to-end test flow completed in sandbox, including simulated webhook events
• ✅ Production API key stored securely (environment variable, not hardcoded)
• ✅ Rate limit headers monitored and alerting configured

The GSMA's eSIM specification and ETSI's remote SIM provisioning standards underpin the provisioning infrastructure that Simology builds on — so the activation codes and ICCID formats you'll encounter in API responses follow globally standardized formats, making your integration portable and future-proof.

If you run into issues during integration, the Simology Partner Support team is available via the dashboard or at partners@simology.io. The sandbox is always open — so build confidently, test thoroughly, and launch knowing your travelers will be connected the moment they land.