paiment 0.2.0

Official Python SDK for the Paiment billing API

paiment (Python SDK)

Official Python SDK for the Paiment billing API.

npm users: install @paiment/sdk instead. This package is the Python equivalent.

Use it in your backend to register subscribers, report LLM usage, and manage plans.

Install

pip install paiment

Python 3.9+.

Setup

Get an API key from Settings → API Keys.

Key format	Notes
tenantId:workspaceId:secret	Recommended
tenantId:secret	Pass workspace_id on the client

from paiment import PaimentClient

client = PaimentClient(api_key="tenantId:workspaceId:secret")
# client = PaimentClient(api_key="...", base_url="http://localhost:5246")

Quick start

from paiment import PaimentClient

with PaimentClient(api_key="tenantId:workspaceId:secret") as client:
    sub = client.subscriptions.create(
        user_id="user_123",
        plan_name="Pro",
        price=2999,
        currency="USD",
        interval="monthly",
    )

    client.usage.report(
        user_id="user_123",
        input_tokens=1250,
        output_tokens=340,
        provider="openai",
        model="gpt-4o",
        plan_id=sub.plan_id,
    )

    client.subscriptions.end(sub.id)

Async

from paiment import AsyncPaimentClient

async with AsyncPaimentClient(api_key="tenantId:workspaceId:secret") as client:
    sub = await client.subscriptions.create(
        user_id="user_123",
        plan_name="Pro",
        price=2999,
        currency="USD",
        interval="monthly",
    )
    await client.usage.report(
        user_id="user_123",
        input_tokens=1250,
        output_tokens=340,
        provider="openai",
        model="gpt-4o",
    )

API reference

Subscriptions

Method	Description
create(user_id, plan_name, price, currency, interval, ...)	New subscription
list(user_id=..., status=...)	List subscriptions
get(subscription_id)	Get by id
update(subscription_id, data)	Patch subscription
end(subscription_id)	Close subscription
cancel(subscription_id)	End immediately

Users

Method	Description
create(user_id, plan_name, price, currency, interval, ...)	User + subscription shortcut
get(user_id)	Get by your user id
list(plan_name=..., page=..., limit=...)	List users
update(user_id, ...)	Partial update
delete(user_id)	Delete user

Usage

Method	Description
report(user_id, input_tokens, output_tokens, provider, model, ...)	Record usage
list(user_id=..., page=..., limit=...)	List usage rows

Plans

Method	Description
create(name, currency, list_price_cents=..., ...)	Create plan
list() / get(id) / update(id, ...) / delete(id)	CRUD

Fields

Field	Meaning
user_id	Your identifier for the end-user
plan_name	Plan catalog name
price	Subscription price in cents
list_price_cents	Catalog list price on plans only

Errors

from paiment import PaimentAuthError, PaimentNotFoundError, PaimentValidationError, PaimentError

Class	HTTP status
PaimentAuthError	401
PaimentNotFoundError	404
PaimentValidationError	400
PaimentError	other