Install & Compatibility
Where this runs
tested against v4.70.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 2.427s · 49.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.7s · import 2.242s · 51MB
50MB installed
● package 50MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AsyncOrb
✓ from orb import AsyncOrb
shared.Security
✓ from orb.models import shared
Used for API key configuration.
DefaultAioHttpClient
✓ from orb import DefaultAioHttpClient
Required when explicitly using aiohttp as the async HTTP client.
This quickstart demonstrates how to initialize both the synchronous `Orb` and asynchronous `AsyncOrb` clients, authenticate using an API key from an environment variable, and create a new customer. It includes an optional configuration for using `aiohttp` with the async client.
import os
import asyncio
from orb import Orb, AsyncOrb
# --- Synchronous Client Example ---
# It's recommended to set your API key as an environment variable: ORB_API_KEY
# For example: os.environ['ORB_API_KEY'] = 'YOUR_ORB_API_KEY'
def sync_example():
client = Orb(
api_key=os.environ.get("ORB_API_KEY", ""),
)
try:
customer = client.customers.create(
email="example-sync@withorb.com",
name="Sync Test Customer",
)
print(f"Synchronous Customer created: {customer.id}")
except Exception as e:
print(f"Synchronous client error: {e}")
# --- Asynchronous Client Example ---
async def async_example():
async with AsyncOrb(
api_key=os.environ.get("ORB_API_KEY", ""),
# http_client=DefaultAioHttpClient(), # Uncomment to use aiohttp
) as client:
try:
customer = await client.customers.create(
email="example-async@withorb.com",
name="Async Test Customer",
)
print(f"Asynchronous Customer created: {customer.id}")
except Exception as e:
print(f"Asynchronous client error: {e}")
if __name__ == "__main__":
sync_example()
asyncio.run(async_example())
Debug
Known issues
breakingThe SDK is in beta, and breaking changes may occur between minor versions without a major version update. It is highly recommended to pin usage to a specific package version to prevent unexpected breaking changes during dependency updates.fixPin your `orb-billing` dependency to an exact version (e.g., `orb-billing==4.55.0`) in your `requirements.txt` or `pyproject.toml`.
affects: All beta versions (e.g., v4.x.x)
gotchaAPI key authentication should ideally be managed via environment variables (e.g., `ORB_API_KEY`) to avoid hardcoding sensitive credentials in source control.fixUse `os.environ.get("ORB_API_KEY")` or similar methods to retrieve the API key at runtime. Ensure `python-dotenv` is used for local development. affects: All versions
gotchaWhen handling webhook requests, the `orb.webhooks.verify_signature` or `orb.webhooks.unwrap` methods require the *raw JSON string* body from the request, not a pre-parsed JSON object. Passing a parsed object will result in signature verification failures.fixEnsure the raw `bytes` or `str` body of the incoming webhook request is passed directly to the webhook verification methods.
affects: All versions
gotchaThe library raises specific exceptions for API connection issues (`orb.APIConnectionError`) and non-success HTTP status codes (`orb.APIStatusError`). Generic `Exception` handling might miss specific error details.fixImplement explicit `try...except` blocks for `orb.APIConnectionError` and `orb.APIStatusError` (which inherits from `orb.APIError`) to handle API-specific errors gracefully and inspect `status_code` and `response` properties.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'orb'
The `orb-billing` package has not been installed or is incorrectly installed, or the import statement uses the wrong module name.
fixInstall the library using `pip install orb-billing` and ensure the import statement is `from orb import Orb` (or `from orb import AsyncOrb` for the async client).
orb.AuthenticationError: 401 Unauthorized
The provided API key is missing, invalid, or does not have the necessary permissions to access the Orb API.
fixEnsure the `ORB_API_KEY` environment variable is set with a valid Orb API key, or pass the correct `api_key` argument when initializing the `Orb` or `AsyncOrb` client.
orb.APIStatusError: 400 BadRequestError
The Orb API returned a client error (4xx) or server error (5xx) status code due to issues like invalid request parameters, a resource not found, or an internal server problem.
fixImplement `try...except orb.APIStatusError as e` to catch the error, then inspect `e.status_code` and `e.response.text` (or `e.response.json()`) to get details from the API on why the request failed and adjust your request accordingly.
TypeError: Argument 'X' has invalid type 'Y', expected 'Z'
A parameter passed to an `orb-billing` SDK method or a nested request parameter (TypedDict) has an incorrect Python data type, which violates the SDK's type strictness.
fixConsult the Orb API documentation or the SDK's type hints for the specific method to ensure all arguments and nested dictionary values are of the expected Python type (e.g., `str`, `int`, `dict`, `list`).
Upgrade
Version history
4.70.1latest on PyPI · released Aug 28, 2026
Audit
Dependencies
httpxrequiredDefault HTTP backend for both synchronous and asynchronous clients.
aiohttpoptionalOptional HTTP backend for improved concurrency performance with the asynchronous client.