Python SDK source

The Python SDK source is part of the Ledger repository. It is not published to PyPI or publicly distributed yet. Use the cURL quickstart for a runnable public integration. The API reference includes a Python SDK source example for every endpoint.

Install from a source checkout

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

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.

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

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

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 provides cURL, Python, and TypeScript examples for the exact body and responses of each endpoint.

Getting started

Concepts

About

Python SDK source

Install from a source checkout

Handle an API error

​Install from a source checkout

​Handle an API error

Install from a source checkout

Handle an API error