> ## Documentation Index
> Fetch the complete documentation index at: https://docs.integrateledger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK source

> Call Ledger from a Python backend with a small, dependency-free client.

The Python SDK source is part of the Ledger repository. **It is not published to PyPI or publicly distributed yet.** Use the [cURL quickstart](https://docs.integrateledger.com/quickstart.md) for a runnable public integration. The API reference includes a Python SDK source example for every endpoint.

The unreleased wheel and source archive are built and installed in a clean consumer during CI. Public installation instructions will be added after registry publication is verified.

## Install from a source checkout

If you have access to the Ledger source repository, install the package from its folder:

```bash theme={null}
python3 -m pip install /absolute/path/to/ledger/packages/sdk-python
```

The package uses Python 3.9+ and the standard library for HTTP; it does not add runtime dependencies. Keep your API key on your server.

The key selects the environment: `ledger_test_` accesses Sandbox and `ledger_live_` accesses Live. Use the same client methods for either environment and keep the keys in separate server-side variables. See [Sandbox and live environments](https://docs.integrateledger.com/environments.md).

```python theme={null}
import os
from ledger_sdk import Ledger

ledger = Ledger(api_key=os.environ["LEDGER_API_KEY"])
ledger.create_feature(id="api_call", name="API call", credit_cost=1)
ledger.create_plan(id="starter", name="Starter", monthly_credits=100, monthly_price_cents=1900)
ledger.create_add_on(id="extra_credits", name="Extra credits", credit_amount=50, price_cents=500)
ledger.create_or_get_customer(customer_id="user_123")
customer = ledger.get_customer(customer_id="user_123")
subscriptions = ledger.list_customer_subscriptions(customer_id="user_123")
purchases = ledger.list_customer_purchases(customer_id="user_123")
active_paid = next((item for item in subscriptions["items"] if item["status"] == "active" and item["monthlyPriceCents"] > 0), None)
if active_paid:
    ledger.set_subscription_cancellation(customer_id="user_123", subscription_id=active_paid["id"], cancel_at_period_end=True)
```

Python methods use `snake_case` names and arguments. The client sends Ledger's documented JSON field names, including `request_id` for usage tracking. Each method returns the parsed JSON response as a dictionary.

## Handle an API error

```python theme={null}
from ledger_sdk import LedgerAPIError, LedgerConnectionError

try:
    result = ledger.track_usage(customer_id="user_123", feature_id="api_call", request_id="operation_123")
except LedgerAPIError as error:
    if error.code == "insufficient_credits":
        # Offer a plan upgrade or a credit pack.
        pass
    else:
        raise
except LedgerConnectionError:
    # Retry with the same request_id after connectivity returns.
    raise
```

`LedgerAPIError` exposes `status`, `code`, and the parsed response `body`. Connection failures raise `LedgerConnectionError`. For plan upgrades, reuse one `idempotency_key` for retries of the same intended upgrade.

The [API reference](https://docs.integrateledger.com/api-reference/plans/create.md) provides cURL, Python, and TypeScript examples for the exact body and responses of each endpoint.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.