> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.paymentkit.com/guides/integration/sdk-reference/python/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.paymentkit.com/_mcp/server.

# Python SDK

The official Python SDK for PaymentKit.

## Installation

```bash
pip install payment-kit
```

## Quick Start

```python
from payment_kit import PaymentKit

client = PaymentKit(
    token="YOUR_API_TOKEN",
    base_url="https://app.paymentkit.com",
)

# Create a customer
customer = client.customers.create_customer(
    account_id="acc_prod_abc123",
    email="customer@example.com",
)

# Create a subscription
from datetime import datetime

subscription = client.subscriptions.create_subscription(
    account_id="acc_prod_abc123",
    customer_id=customer.id,
    period_start=datetime.now(),
    items=[{"price_id": "prc_prod_xyz789", "quantity": 1}],
)

# List invoices
invoices = client.invoices.list_invoices(
    account_id="acc_prod_abc123",
    limit=10,
)
```

## Environment

All API requests use the production base URL:

```python
client = PaymentKit(
    token="YOUR_API_TOKEN",
    base_url="https://app.paymentkit.com",
)
```

Sandbox accounts also use `https://app.paymentkit.com` with sandbox API tokens.

## Async Client

The SDK provides an async client for non-blocking API calls:

```python
import asyncio
from payment_kit import AsyncPaymentKit

client = AsyncPaymentKit(
    token="YOUR_API_TOKEN",
    base_url="https://app.paymentkit.com",
)

async def main():
    customer = await client.customers.create_customer(
        account_id="acc_prod_abc123",
        email="customer@example.com",
    )
    print(customer.id)

asyncio.run(main())
```

## Error Handling

```python
from payment_kit.core.api_error import ApiError

try:
    customer = client.customers.create_customer(...)
except ApiError as e:
    print(e.status_code)
    print(e.body)
```

## Configuration

### Timeouts

Default timeout is 60 seconds. Override at client or request level:

```python
# Client-level timeout
client = PaymentKit(
    token="YOUR_API_TOKEN",
    base_url="https://app.paymentkit.com",
    timeout=30.0,
)

# Request-level timeout
customer = client.customers.create_customer(
    ...,
    request_options={"timeout_in_seconds": 10}
)
```

### Retries

The SDK automatically retries requests with exponential backoff for:

* 408 (Request Timeout)
* 409 (Conflict)
* 429 (Too Many Requests)
* 5XX (Server Errors)

```python
# Configure max retries per request (default is 2)
customer = client.customers.create_customer(
    ...,
    request_options={"max_retries": 3}
)
```

## Resources

* [PyPI Package](https://pypi.org/project/payment-kit/)
* [GitHub Repository](https://github.com/payment-kit/payment-kit-python)
* [Full SDK Reference](https://github.com/payment-kit/payment-kit-python/blob/main/reference.md)