Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

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

  • Amounts are { amount, currency }. price is what OpenRoam charges you, value what your customer receives.
  • Full API documentation: https://openroam.com (partner portal). Support: support@openroam.com.

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.

Metadata

Release files for openroam 0.1.0rc6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for openroam 0.1.0rc6
File Size Uploaded Provenance Actions
openroam-0.1.0rc6.tar.gz 263.4 kB With provenance Details for openroam-0.1.0rc6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for openroam 0.1.0rc6
File Interpreter ABI Platform Actions
openroam-0.1.0rc6-py3-none-any.whl Python 3 none any Details for openroam-0.1.0rc6-py3-none-any.whl

Total release size: 980.2 kB

Release files / openroam-0.1.0rc6.tar.gz

Download URL openroam-0.1.0rc6.tar.gz
Size 263.4 kB
Tags Source
SHA-256 checksum
How to use checksums
acd00bf690566a416156bfaf67da8f0c0f9d5a2b9c13e479751c4364471431ad
BLAKE2b-256 checksum
How to use checksums
19cd835fd7920e217ea6a80eb2c86574583ad80c64fbd4b4de17949b4fbab0ec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / openroam-0.1.0rc6-py3-none-any.whl

Download URL openroam-0.1.0rc6-py3-none-any.whl
Size 716.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1eae942ce0a0a7356635dce60c732c3dcf0522dfdde7f089a37bc77a1fa2aa71
BLAKE2b-256 checksum
How to use checksums
cdc0a3ec87ad245bd7303725b848bbb20e2b7b6b43040b902c0bf5c15e0bf190
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for openroam 0.1.0rc6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for openroam-0.1.0rc6.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page