Metadata-Version: 2.4
Name: creem
Version: 0.2.1
Summary: Python SDK for the Creem.io REST API
Author-email: AJ Gonzalez <aj.gonzalez.dev@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/AJ-Gonzalez/creem-python
Project-URL: Source, https://github.com/AJ-Gonzalez/creem-python
Project-URL: Issues, https://github.com/AJ-Gonzalez/creem-python/issues
Project-URL: Documentation, https://docs.creem.io/api-reference
Keywords: creem,payments,merchant-of-record,subscriptions,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pylint>=3.2; extra == "dev"
Requires-Dist: flake8>=7; extra == "dev"
Requires-Dist: fastapi>=0.115; extra == "dev"
Requires-Dist: uvicorn>=0.30; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Dynamic: license-file

# Unofficial Creem.io Python SDK

A comfy python wrapper around the Creem REST API. 

Will hopefully be official at some point. 

## Installing

Requires Python 3.11+.

```bash
pip install creem
```

For development, install from the repo with test tooling:

```bash
pip install -e ".[dev]"
```

## Quickstart

Grab your API key from the [dashboard](https://creem.io/dashboard/developers), then:

```python
from creem import Creem

creem = Creem()  # reads CREEM_API_KEY from the environment
```

Test keys (`creem_test_...`) automatically target the sandbox at `test-api.creem.io` — no config needed. Live keys (`creem_...`) hit production.

**Sell something.** Create a checkout session and send your customer to the hosted payment page:

```python
checkout = creem.checkouts.create({
    "product_id": "prod_abc123",
    "success_url": "https://yourapp.com/success",
    "metadata": {"userId": "user_123"},  # flows through to webhooks
})

print(checkout["checkout_url"])  # redirect the customer here
```

**Know when it's paid.** Handle the `checkout.completed` (one-time) and `subscription.paid` (recurring) webhooks to grant access — the payloads carry your `metadata` back. Signatures are verified for you:

```python
from creem import WebhookHandler

handler = WebhookHandler(secret="your webhook secret")
handler.on("subscription.paid", grant_access)
handler.on("subscription.canceled", revoke_access)

# FastAPI: handler.handle(await request.body(), request.headers.get("creem-signature"))
# Async callbacks: await handler.ahandle(...)
```

**Keep customers happy.** Cancel at period end, not instantly:

```python
creem.subscriptions.cancel("sub_abc123", {"mode": "scheduled"})
```

Every response is a typed dict with full field hints. When the API complains, you get a `CreemAPIError` carrying the `trace_id` — include it when contacting support.

Retries are automatic: rate limits (429), server errors, and network failures are retried up to 3 times with exponential backoff and jitter — when it's safe to do so (GETs and requests carrying `request_id`, `idempotency_key`, or an `Idempotency-Key` header). Pass `max_retries=0` to `Creem(...)` to disable.

## Examples

Runnable scripts live in [`examples/`](examples/) — set `CREEM_API_KEY` (test keys target the sandbox) and run them directly:

| Example | What it shows |
|---|---|
| `checkout_flow.py` | Create a product, create a checkout, print the payment URL |
| `subscription_management.py` | Search, scheduled cancel, pause, resume |
| `webhook_server.py` | FastAPI endpoint with signature verification and grant/revoke dispatch |
| `customer_credits.py` | Wallet: create account, credit, balance |
| `browse_and_paginate.py` | Pagination iterators over products and transactions |

```bash
CREEM_API_KEY=creem_test_... python examples/checkout_flow.py
```

## API Reference

See the full reference in [API_REFERENCE](API_REFERENCE.md)

## Documentation for Agents

AI agents integrating or extending this SDK should read [docs/for-agents.md](docs/for-agents.md) — it covers the mental model, conventions, integration flows, and gotchas. For the complete API contract, see [API_REFERENCE.md](API_REFERENCE.md).
