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+.

pip install creem

For development, install from the repo with test tooling:

pip install -e ".[dev]"

Quickstart

Grab your API key from the dashboard, then:

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. Async backends use AsyncCreem — same API, everything awaited (await creem.checkouts.create(...)).

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

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:

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:

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

Every response is a typed dict with full field hints (models import from the top level: from creem import Checkout, Subscription, ...). 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/ — set CREEM_API_KEY (test keys target the sandbox) and run them directly:

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

API Reference

See the full reference in API_REFERENCE

Documentation for Agents

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