Orb Billing Python SDK

4.55.0 · active · verified Mon Apr 13

The orb-billing library is the official Python client SDK for accessing the Orb REST API, which provides a modern pricing platform for subscription and usage-based billing. It offers both synchronous and asynchronous clients, built on `httpx`, with type definitions for request parameters and response fields. Currently, at version 4.55.0, the SDK is in beta and receives frequent updates, often with new features and API changes.

Warnings

breaking The 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.
Fix: Pin your `orb-billing` dependency to an exact version (e.g., `orb-billing==4.55.0`) in your `requirements.txt` or `pyproject.toml`.
gotcha API key authentication should ideally be managed via environment variables (e.g., `ORB_API_KEY`) to avoid hardcoding sensitive credentials in source control.
Fix: Use `os.environ.get("ORB_API_KEY")` or similar methods to retrieve the API key at runtime. Ensure `python-dotenv` is used for local development.
gotcha When 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.
Fix: Ensure the raw `bytes` or `str` body of the incoming webhook request is passed directly to the webhook verification methods.
gotcha The 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.
Fix: Implement 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.

Install

pip install orb-billing Default synchronous and asynchronous client
pip install orb-billing[aiohttp] Asynchronous client with aiohttp backend

Imports

Orb
```
from orb import Orb
```
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.

Quickstart

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())

view raw JSON →