OpenRoam SDK for Python

Official client for the OpenRoam Partner API: eSIMs, airtime, utility payments, gift cards, hotels and flights. Python 3.11+.

Install

pip install openroam==0.1.0-rc.6

This is a release candidate: install it by its exact version, as above; a plain install does not pick it up. Before 1.0 the API can change between minor versions; every change is listed in the changelog.

Quick start

import os
from openroam import OpenRoam

openroam = OpenRoam(os.environ["OPENROAM_API_KEY"])  # or OpenRoam() with OPENROAM_API_KEY set

found = openroam.esims.search(country_code="JP")
quote = openroam.esims.quote({"currency": "USD", "items": items})
order = openroam.esims.order({"currency": "USD", "items": items})

openroam.esims.get_usage(iccid)
openroam.hotels.search({...})

Every product is an attribute of the client: esims, airtime, utilities, gift_cards, hotels, flights, plus orders, order_items, wallets, currencies, countries and mobile_networks. Buying always reads search, quote, order; get fetches one thing you own, list_... returns many, everything else starts with a verb. A path id is the first argument, a body is passed as it is (a dict with the API's field names, or the model, such as openroam.EsimOrderRequest), and query parameters are keyword arguments. Answers are models: found.items, found.pagination.

Options when you need them:

openroam = OpenRoam(
    api_key="key",
    environment="sandbox",  # default "production"
    max_retries=3,          # default 0: no retries
    # base_url="https://..." to point anywhere else, for example a development host
)

openroam.esims.search(country_code="JP", timeout=10)  # every call takes a timeout, in seconds

Orders are safe to repeat

An idempotency key means: if the same request arrives twice, OpenRoam makes one order, not two. order() creates a key for you on every call. To stay safe even if your own program crashes and asks again, pass a UUID generated once and persisted for that purchase, for example your order id if it is a UUID:

openroam.esims.order(body, idempotency_key=my_order_id)

Errors

A failed call raises an OpenRoamError with the error body of the API: status, code (branch on this), name, message, request_id (keep it for support) and details (a list of dicts with path, reason and message). When no answer arrived (network error, timeout), status is None and __cause__ is the original error.

from openroam import OpenRoam, OpenRoamError

try:
    openroam.esims.order(body)
except OpenRoamError as error:
    if error.code == 11002:
        ...  # the price rose above your maxPrice
    else:
        raise

Lists and pages

Pagination depends on the method. esims.search accepts page and limit and returns items and pagination, while orders.list returns orders and pagination. esims.list_catalog accepts cursor and limit and returns items and next_cursor; pass next_cursor as cursor to fetch the next page. Some lists, such as esims.list_compatible_devices, return a plain list.

Webhooks

from openroam import verify_webhook, WebhookSignatureError

verify_webhook(
    secret=os.environ["OPENROAM_WEBHOOK_SECRET"],
    timestamp=headers["X-OpenRoam-Timestamp"],
    event_id=headers["X-OpenRoam-Event-Id"],
    signature=headers["X-OpenRoam-Signature"],
    raw_body=request_body,  # the body exactly as received, before JSON parsing
)  # raises WebhookSignatureError when invalid or older than 5 minutes

Retries

Retries are off by default. Set max_retries to retry network errors, 429, 502/503/504 and "still running" (12002) safely: a POST is sent again only with its Idempotency-Key, the same key and the same body, and order() always has one.

openroam = OpenRoam(api_key, max_retries=3)

The full behaviour: Retries and idempotency. enable_retries and new_idempotency_key (in openroam.retry) are also exported if you build your own requests.

Good to know

The client is generated from the OpenRoam Partner API description, so it always matches the API; webhooks, retry and the errors are hand-written. MIT licensed.