nxtl-esim
Python SDK for the NXTL eSIM B2B API. Issue and manage pay-as-you-go travel eSIMs, read the pooled balance, and verify signed webhooks.
Create a business account and API key at NXTL for Business. Operation details are in the API reference. This package tracks OpenAPI 2.6.3 (48 operations) at https://nxtlsim.com/api/v1.
pip install nxtl-esim
Python 3.9 or newer. The only runtime dependency is httpx. Sync and async clients share one operation surface.
Quick start
import os
from nxtl_esim import NxtlClient, fulfil_esim_order
with NxtlClient(os.environ["NXTL_API_KEY"]) as nxtl:
nxtl.health()
nxtl.partner()
order = fulfil_esim_order(
nxtl,
client_reference="ORDER-123",
nickname="Traveller 123",
tier="cheapest",
idempotency_key="order-123-esim",
)
print(order["activation"].get("lpa"))
Async:
import os
from nxtl_esim import AsyncNxtlClient, fulfil_esim_order_async
async with AsyncNxtlClient(os.environ["NXTL_API_KEY"]) as nxtl:
order = await fulfil_esim_order_async(
nxtl,
client_reference="ORDER-123",
nickname="Traveller 123",
tier="cheapest",
idempotency_key="order-123-esim",
)
POST /esims returns 202 and a job_id. The helper estimates, queues the eSIM, and polls GET /jobs/{id}. Do not treat the 202 body as a provisioned profile.
tier is cheapest or best_coverage. The alias standard is accepted by the API and stored as cheapest.
Client options
Timeouts and retry delays are seconds.
NxtlClient(
api_key, # omitted only for GET /health
base_url="https://nxtlsim.com/api/v1",
timeout=30.0, # seconds
http_client=None, # your httpx.Client; not closed by the SDK
user_agent="nxtl-esim/0.1.0 (+https://nxtlsim.com)",
logger=None, # object with debug/info/warn/error
retry=None, # mapping, or False to disable
headers=None, # extra headers; X-NXTL-Key still comes from api_key
idempotency_header="Idempotency-Key", # or "X-NXTL-Idempotency-Key"
auto_idempotency_key=True, # POST /esims, /esims/bulk-issue, /topup
accept_currency=None, # TODO(spec): human reference only, not in OpenAPI
)
AsyncNxtlClient takes the same arguments and an httpx.AsyncClient. Redirects are not followed, so the API key is not sent to another host. Pass a client you already configured if you need different transport behaviour.
Per-call options mapping: idempotency_key, headers, timeout (seconds), retry.
Retries
HTTP 429 is retried. HTTP 5xx and transport errors are retried for GET, HEAD, PUT, and DELETE, and for any call that sent an idempotency key. Other POST and PATCH calls are not retried on 5xx unless retry_unsafe is true.
Delay is full jitter between 0 and min(max_delay, base_delay * 2^attempt). Retry-After is a minimum, capped by max_retry_after (default 120 seconds).
| Retry key | Default | Unit |
|---|---|---|
max_retries |
2 | extra attempts |
base_delay |
0.2 | seconds |
max_delay |
8 | seconds |
max_retry_after |
120 | seconds |
retry_unsafe |
false | |
sleep |
time.sleep or asyncio.sleep |
|
random |
random.random |
[0, 1) |
Responses
Methods return ApiResponse: data, status_code, headers, request_id, idempotent_replayed, rate_limit, idempotency_key.
request(method, path, query=..., json_body=..., options=...) is the escape hatch.
Published constraints (iccid length, quantity, amount_usd, nickname length, tier, threshold enums) raise ValueError before a request is sent.
Errors
| Class | When |
|---|---|
NxtlAuthError |
401, or a missing API key |
NxtlAccessDeniedError |
403 |
NxtlValidationError |
400 |
NxtlInsufficientBalanceError |
402 |
NxtlNotFoundError |
404 |
NxtlConflictError |
409 |
NxtlQuotaExceededError |
409 quota_exhausted |
NxtlRateLimitError |
429 |
NxtlServerError |
5xx |
NxtlConnectionError / NxtlTimeoutError |
transport / timeout |
NxtlJobFailedError |
polled job failed |
NxtlWebhookError |
signature or envelope rejected |
Attributes: status_code, code, error_type, request_id, doc_url, details, headers, body, retry_after. Keep request_id for support at support@nxtlsim.com.
Operations
| Method | HTTP |
|---|---|
health |
GET /health |
partner |
GET /partner |
quotas |
GET /quotas |
audit / iterate_audit |
GET /audit |
list_esims / iterate_esims |
GET /esims |
issue_esim |
POST /esims (idempotent) |
list_lines / iterate_lines |
GET /lines (legacy) |
get_esim |
GET /esims/{iccid} |
update_nickname |
PATCH /esims/{iccid}/nickname |
update_tier |
PATCH /esims/{iccid}/tier |
update_status |
PATCH /esims/{iccid}/status |
suspend_esim |
POST /esims/{iccid}/suspend |
resume_esim |
POST /esims/{iccid}/resume |
get_wallet |
GET /esims/{iccid}/wallet |
get_esim_usage |
GET /esims/{iccid}/usage |
get_esim_events |
GET /esims/{iccid}/events |
bulk_status |
POST /esims/bulk-status (max 100) |
bulk_tier |
POST /esims/bulk-tier (max 1000) |
bulk_issue |
POST /esims/bulk-issue (idempotent) |
estimate |
POST /esims/estimate |
list_jobs |
GET /jobs |
get_job |
GET /jobs/{id} |
get_esim_request |
GET /esim-requests/{job_id} (legacy) |
get_balance |
GET /balance |
list_balance_history / iterate_balance_history |
GET /balance/history |
topup |
POST /topup (idempotent, prepaid budget, no card charge) |
list_invoices |
GET /invoices |
usage_summary |
GET /usage/summary |
usage_esims |
GET /usage/esims |
usage_lines |
GET /usage/lines (legacy, no query params in the spec) |
usage_cdrs / iterate_usage_cdrs |
GET /usage/cdrs |
usage_timeseries |
GET /usage/timeseries |
list_api_keys |
GET /api-keys |
create_api_key |
POST /api-keys (secret once) |
revoke_api_key |
DELETE /api-keys/{key_public} |
get_webhooks |
GET /webhooks |
update_webhooks |
PUT /webhooks |
list_webhook_events |
GET /webhooks/events |
get_webhook_secret |
GET /webhooks/secret |
test_webhook |
POST /webhooks/test |
list_webhook_deliveries / iterate_webhook_deliveries |
GET /webhooks/deliveries |
get_webhook_delivery |
GET /webhooks/deliveries/{id} |
replay_webhook_delivery |
POST /webhooks/deliveries/{id}/replay |
replay_webhook_delivery_legacy |
POST /webhooks/{id}/replay |
list_thresholds |
GET /thresholds |
create_threshold |
POST /thresholds |
update_threshold |
PATCH /thresholds/{id} |
delete_threshold |
DELETE /thresholds/{id} |
API_OPERATIONS exports the same 48 entries. Scope names from the API reference (esims:read, esims:write, balance:read, balance:write, keys:read, keys:write, webhooks:read, webhooks:write, thresholds:read, thresholds:write, audit:read, usage:read) are enforced by the server.
Async methods have the same names and are awaited: await client.issue_esim(...). Async iterators are iterate_esims, iterate_lines, iterate_audit, iterate_balance_history, iterate_usage_cdrs, and iterate_webhook_deliveries.
Webhooks
from nxtl_esim import construct_webhook_event, SIGNATURE_HEADER
event = construct_webhook_event(
payload=raw_body, # bytes or the exact UTF-8 string
signature_header=headers[SIGNATURE_HEADER],
secret=[active_secret, rotating_secret],
tolerance_seconds=300, # 0 skips the timestamp check
)
verify_webhook_signature returns a bool. parse_webhook_event requires id, event, integer timestamp, and object data. WEBHOOK_EVENT_NAMES lists the 15 names in the human reference. The schema types event as a string, so other names still parse. Read the live catalog with list_webhook_events().
The signature is HMAC-SHA256 of {timestamp}.{raw_body} as described in the API reference. The OpenAPI text names the header and the algorithm.
Reseller helpers
Markup runs locally. It does not call the API and does not convert currencies (fx_applied is always false). Public feed rates are EUR per GB. Issuance cost against the pooled balance comes from estimate and quotas.
from nxtl_esim import quote_price, format_currency, PublicCatalog
quote = quote_price(
2.5,
{
"mode": "tiered", # percentage, fixed, or tiered
"percentage": 30,
"fixed": 0.5,
"rounding": "0.99", # none, nearest, up, down, 0.99, 0.95, 0.00
"currency": "EUR",
"tiers": [
{"up_to": 5, "percentage": 40},
{"up_to": 20, "percentage": 25},
{"up_to": None, "percentage": 15},
],
"country_overrides": {"JP": {"mode": "percentage", "percentage": 50}},
},
country="FR",
locale="en_US",
)
upTo is accepted as an alias of up_to. Charm rounding selects the smallest amount at or above the raw retail with cents .99, .95, or .00.
catalog = PublicCatalog() # https://nxtlsim.com/ai/*.json
feed = catalog.pricing()
retail = catalog.quote_country_rate(feed, "FR", {"percentage": 40, "rounding": "0.99"})
Also coverage(), destinations(), product(), load_all(), and AsyncPublicCatalog. Options: origin, timeout (seconds), user_agent, http_client, retry.
from nxtl_esim import (
assess_balance,
collect_usage,
ensure_balance_threshold,
submit_and_collect_bulk_issue,
)
assess_balance(nxtl, low_usd=25, exhausted_usd=0)
ensure_balance_threshold(nxtl, threshold_value=25, action="notify")
collect_usage(nxtl, days=7, include_cdrs=True)
submit_and_collect_bulk_issue(
nxtl,
{"quantity": 10, "tier": "cheapest", "client_reference": "BATCH-9"},
idempotency_key="batch-9",
)
assess_balance uses status="unknown" when no candidate amount key is present. sum_usage_amounts sets zero_is_not_free when one of amount_usd / amount_eur is zero and the other is not.
Reseller layer
Customer records, packages, wallets, and customer invoices live in your process. NXTL eSIM is pay-as-you-go on a pooled balance. It does not store your customers or the packages you sell. API keys come from NXTL for Business. Import the helpers from nxtl_esim.reseller. Async network calls are load_usage_details_async, AsyncCustomerDirectory, sync_reseller_async, and provision_customers_async.
Usage and cost
load_usage_details reads GET /usage/cdrs and, for one ICCID, GET /esims/{iccid}/usage. Periods are daily, monthly, or a custom range. include_partner_rollups=True also calls summary, per-eSIM, and timeseries. Those last two day-count endpoints are capped at 365 days.
Reconciled cost uses the native field selected by currency. Current usage is EUR: amount_eur is a signed retail pool debit and amount_usd is 0. That zero is not an FX conversion and is not free usage. The positive value is the NXTL API charge (reseller acquisition cost), not upstream wholesale. Markup sits on top of it. The public per-GB feed is only for quote_trip, not for reconciled charges.
Reseller sync requests accounting=1. Without it, CDR bytes and network text stay empty and are not measured zero. detail_available false stays pending. True with bytes 0 is measured zero. after_id is an ascending cursor (id > after_id, page 1, next_cursor or null). Checkpoints are per account, ICCID, and date window, and they move only after the commit. sync_reseller_async uses that same commit path. A webhook without data.ledger_id is not charged. Markup and FX apply to the selling charge. Missing FX stays unresolved. Credits are the acquisition amount with no markup. JSON replacement is atomic and single-process. SQL commit_sync requires a transaction. Germany maps to DE. A manual pause is not resumed. POST /esims 202 is not completed provisioning.
Customers
MemoryCustomerStore is the default. JsonFileCustomerStore writes one JSON file. SqlCustomerStore sends CUSTOMER_STORE_SQL through your query(sql, params) callable. Placeholders are ?.
directory = CustomerDirectory(MemoryCustomerStore(), nxtl)
customer = directory.save_customer({"id": "cus_1", "name": "Ada", "external_id": "crm-1", "tags": ["vip"]})
directory.assign_line(customer["id"], iccid, "handset")
directory.credit(customer["id"], 40, "EUR", "prepaid wallet")
directory.suspend_customer(customer["id"]) # POST /esims/{iccid}/suspend
flag_customer only updates the store. Wallet credits and debits do not call POST /topup.
Packages
define_package with a name such as Europe 5GB 30 days, a data cap, validity, country list, and price is your product. open_allocation starts it. apply_usage_to_packages consumes bytes FIFO or by priority. top_up_allocation and renew_allocation extend the store record.
overage="suspend" can call suspend_overage_lines. sync_package_threshold posts line_usage_usd_today only when usd_cap is set. A gigabyte allowance is not a published threshold metric, so the cap is tracked in the store.
Billing
build_customer_invoice emits usage, markup, and package-fee lines. invoices_to_csv and invoices_to_json export them. build_statement includes wallet movement. margin_report sums revenue, cost, and margin. convert_fx uses your rates: base USD and rates["EUR"] = 1.1 means 1 EUR = 1.1 USD.
Monitoring
ensure_usage_percent_rule posts line_usage_pct. ensure_pool_balance_rule posts balance_below. WebhookRouter.on handles the event names in WEBHOOK_EVENT_NAMES, including usage.recorded, balance.low, job.completed, and esim.provisioned. sync_reseller polls active lines, snapshots usage, debits the retail delta, applies packages, and raises low-balance and overage alerts. sync_loop is a local async timer.
Catalog, quotes, provisioning, lifecycle, audit
search_catalog filters pricing, destinations, and coverage by country, text, and max EUR per GB. Region search matches destination rows of type region and does not expand them to ISO codes.
quote_trip prices the public per-GB feed. split="even" divides gigabytes across countries. split="each" prices the full amount in every country. issuance_fee is optional and should come from estimate or quotas.
provision_customers calls POST /esims per customer. Bulk issue uses one client_reference for the batch, so it is not used for a customer list. wait=True polls the job and assigns the ICCID when the payload contains one.
LineLifecycle covers issue, status, suspend, resume, terminate, wallet, events, and pool_topup. Terminate is permanent. There is no DELETE and no per-line top-up. read_audit walks GET /audit.
Examples
- FastAPI fulfilment:
examples/fastapi-fulfilment/main.py. - Monthly billing export:
examples/monthly-billing/export.py.
Release
Push a tag py-vX.Y.Z. The workflow sets the version from the tag and publishes with PyPI trusted publishing (pypa/gh-action-pypi-publish). Configure the publisher for this repository, workflow release-py.yml, and GitHub environment pypi (the workflow's environment name). No API token is stored in the workflow.
License
MIT.
Metadata
Release files for nxtl-esim 0.1.0
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 |
|---|---|---|---|---|
| nxtl_esim-0.1.0.tar.gz | 72.8 kB | With provenance | Details for nxtl_esim-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nxtl_esim-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for nxtl_esim-0.1.0-py3-none-any.whl |
Total release size: 143.0 kB
Release files / nxtl_esim-0.1.0.tar.gz
| Download URL | nxtl_esim-0.1.0.tar.gz |
|---|---|
| Size | 72.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8b234c25f7d671fc483dafaadc24183f977f3017ded3758a76170bf0e2e2c370
|
|
BLAKE2b-256 checksum How to use checksums |
7316f1aaa2b1a69bb79dde731056369d20d965273404119a6f58cdcb3989ab0c
|
| 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 5, 2026.
Transparency logRelease files / nxtl_esim-0.1.0-py3-none-any.whl
| Download URL | nxtl_esim-0.1.0-py3-none-any.whl |
|---|---|
| Size | 70.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
604651537ba36671345c1f9a8b6c8c9492c244027f628ff871a77b11cd0959fb
|
|
BLAKE2b-256 checksum How to use checksums |
02fbc1361c265796a695bca77e9ef40449a4e10202fa5ebb0323afd64c888490
|
| 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 5, 2026.
Transparency logSecurity for nxtl-esim 0.1.0
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 nxtl_esim-0.1.0.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 5, 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.