Metadata-Version: 2.4
Name: paiment
Version: 0.2.0
Summary: Official Python SDK for the Paiment billing API
Author: Paiment
License-Expression: MIT
Project-URL: Homepage, https://paiment.tech
Project-URL: Documentation, https://paiment.tech
Keywords: paiment,billing,sdk,llm,usage
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: mypy>=1.9; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# paiment (Python SDK)

Official Python SDK for the [Paiment](https://paiment.tech) 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

```bash
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 |

```python
from paiment import PaimentClient

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

## Quick start

```python
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

```python
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

```python
from paiment import PaimentAuthError, PaimentNotFoundError, PaimentValidationError, PaimentError
```

| Class | HTTP status |
|-------|-------------|
| `PaimentAuthError` | 401 |
| `PaimentNotFoundError` | 404 |
| `PaimentValidationError` | 400 |
| `PaimentError` | other |
