{"id":5354,"library":"orb-billing","title":"Orb Billing Python SDK","description":"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.","status":"active","version":"4.55.0","language":"en","source_language":"en","source_url":"https://github.com/orbcorp/orb-python","tags":["billing","api-client","payments","saas","usage-based","sdk"],"install":[{"cmd":"pip install orb-billing","lang":"bash","label":"Default synchronous and asynchronous client"},{"cmd":"pip install orb-billing[aiohttp]","lang":"bash","label":"Asynchronous client with aiohttp backend"}],"dependencies":[{"reason":"Default HTTP backend for both synchronous and asynchronous clients.","package":"httpx"},{"reason":"Optional HTTP backend for improved concurrency performance with the asynchronous client.","package":"aiohttp","optional":true}],"imports":[{"symbol":"Orb","correct":"from orb import Orb"},{"symbol":"AsyncOrb","correct":"from orb import AsyncOrb"},{"note":"Used for API key configuration.","symbol":"shared.Security","correct":"from orb.models import shared"},{"note":"Required when explicitly using aiohttp as the async HTTP client.","symbol":"DefaultAioHttpClient","correct":"from orb import DefaultAioHttpClient"}],"quickstart":{"code":"import os\nimport asyncio\nfrom orb import Orb, AsyncOrb\n\n# --- Synchronous Client Example ---\n\n# It's recommended to set your API key as an environment variable: ORB_API_KEY\n# For example: os.environ['ORB_API_KEY'] = 'YOUR_ORB_API_KEY'\n\ndef sync_example():\n    client = Orb(\n        api_key=os.environ.get(\"ORB_API_KEY\", \"\"),\n    )\n    try:\n        customer = client.customers.create(\n            email=\"example-sync@withorb.com\",\n            name=\"Sync Test Customer\",\n        )\n        print(f\"Synchronous Customer created: {customer.id}\")\n    except Exception as e:\n        print(f\"Synchronous client error: {e}\")\n\n# --- Asynchronous Client Example ---\n\nasync def async_example():\n    async with AsyncOrb(\n        api_key=os.environ.get(\"ORB_API_KEY\", \"\"),\n        # http_client=DefaultAioHttpClient(), # Uncomment to use aiohttp\n    ) as client:\n        try:\n            customer = await client.customers.create(\n                email=\"example-async@withorb.com\",\n                name=\"Async Test Customer\",\n            )\n            print(f\"Asynchronous Customer created: {customer.id}\")\n        except Exception as e:\n            print(f\"Asynchronous client error: {e}\")\n\nif __name__ == \"__main__\":\n    sync_example()\n    asyncio.run(async_example())\n","lang":"python","description":"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."},"warnings":[{"fix":"Pin your `orb-billing` dependency to an exact version (e.g., `orb-billing==4.55.0`) in your `requirements.txt` or `pyproject.toml`.","message":"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.","severity":"breaking","affected_versions":"All beta versions (e.g., v4.x.x)"},{"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.","message":"API key authentication should ideally be managed via environment variables (e.g., `ORB_API_KEY`) to avoid hardcoding sensitive credentials in source control.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the raw `bytes` or `str` body of the incoming webhook request is passed directly to the webhook verification methods.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}