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.

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",
        external_plan_id="price_pro",
        plan_name="Pro",  # optional naming hint
        price=2999,
        currency="USD",
        interval="monthly",
    )

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

    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",
        external_plan_id="price_pro",
        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",
        external_plan_id="price_pro",
    )

API reference

Subscriptions

Users

Usage

Plans

Fields

Errors

from paiment import PaimentAuthError, PaimentNotFoundError, PaimentValidationError, PaimentError

Changelog

0.3.0

• Client plan key is external_plan_id (required on usage, subscriptions, users, plans)
• Removed write-path plan_id; internal ids remain server-owned
• plan_name is an optional naming hint for auto-created plans
• Removed nested usage-based / fixed price fields from plan APIs