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 }.priceis what OpenRoam charges you,valuewhat 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.