codelet 0.2.0

Official Python SDK for the Codelet public API

Codelet Python SDK

Official Python client for the Codelet public API.

Install

pip install codelet

For local development from this monorepo:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Usage

from codelet import Codelet, CodeletError
from codelet.models import CancelSubscriptionRequest

codelet = Codelet(api_key="cl_test_…")  # or cl_live_…

# Ingest (auto idempotency_key when omitted)
codelet.ingest({
    "customer_id": "org_42",
    "metric": "api_call",
    "quantity": "1",
})

me = codelet.account.get_me()
customers = codelet.customers.list_customers()
codelet.subscriptions.cancel_subscription(
    "subs_…",
    CancelSubscriptionRequest(mode="at_period_end"),
)

Optional client options: base_url, retries, headers.

Examples

Create metrics before plans, credit packs, or ingest. Unknown metric names return 400.

Create a metric

from codelet.models import CreateMetricRequest

metric = codelet.metrics.create_metric(
    CreateMetricRequest(
        name="api_request",
        display_name="API Request",
        aggregation="sum",
    )
)

Create a credit pack

from codelet.models import CreateCreditPackRequest

pack = codelet.credit_packs.create_credit_pack(
    CreateCreditPackRequest(
        metric="api_request",
        name="500 API requests",
        price_amount="25.00",
        currency="USD",
        quantity_granted="500",
    )
)

Create and publish a plan

from codelet.models import CreatePlanRequest

plan = codelet.plans.create_plan(
    CreatePlanRequest(
        name="Pro",
        description="Usage-based Pro plan",
        version={
            "currency": "USD",
            "billing_period": "monthly",
            "billing_mode": "postpaid",
            "fixed_fees": [
                {
                    "fee_type": "period_charge",
                    "name": "Platform fee",
                    "amount": "29.00",
                },
            ],
            "usage_fees": [
                {
                    "pricing_model": "unit",
                    "billing_timing": "in_arrears",
                    "included_quantity": "1000",
                    "unit_price": "0.002",
                    "metric": "api_request",
                },
            ],
        },
    )
)

# Drafts are not checkout-ready until published
codelet.plans.publish_plan(plan.id)

Create checkout

Credit pack (one-time purchase):

from codelet.models import CreateCheckoutRequest

pack_checkout = codelet.checkout.create_checkout(
    CreateCheckoutRequest(
        customer_id="org_42",
        pack_id="pack_…",
        success_url="https://yourapp.com/billing/success",
        cancel_url="https://yourapp.com/billing/cancel",
        idempotency_key="purchase:order-123",
    )
)
# Redirect the browser to pack_checkout.checkout_url

Subscription (plan):

plan_checkout = codelet.checkout.create_checkout(
    CreateCheckoutRequest(
        customer_id="org_42",
        plan_id="plan_…",
        success_url="https://yourapp.com/welcome",
    )
)
# Redirect the browser to plan_checkout.checkout_url

Pass either customer_id or customer_email, not both. Exactly one of pack_id or plan_id is required.

API reference

All generated methods are available on the Codelet instance (for example codelet.customers.list_customers). Prefer codelet.ingest(…) over codelet.usage.ingest_event(…) when recording usage; the helper fills idempotency_key when omitted.

codelet.ingest(body)

Ingest a usage event. Same as usage.ingest_event, but generates idempotency_key when omitted. Accepts a dict or IngestEventRequest.

Method	Description
ingest(body)	POST /v1/ingest

Account (codelet.account)

Method	Description
get_me()	API key context (project + environment)

Checkout (codelet.checkout)

Method	Description
create_checkout(create_checkout_request)	Create a credit pack or subscription checkout

Credit packs (codelet.credit_packs)

Method	Description
list_credit_packs(metric=None, active="true", page_size=None, cursor=None)	List packs (default: active only)
create_credit_pack(create_credit_pack_request)	Create a pack
get_credit_pack(pack_id)	Get a pack by ID
update_credit_pack(pack_id, update_credit_pack_request)	Update name, description, and/or active

Customers (codelet.customers)

Method	Description
list_customers(page_size=None, cursor=None)	List customers
create_customer(create_customer_request)	Create a customer
get_customer(customer_id)	Get a customer
update_customer(customer_id, update_customer_request)	Update editable fields
get_customer_balance(customer_id, metric=None)	Credit balances (all metrics, or one)

Metrics (codelet.metrics)

Method	Description
list_metrics(page_size=None, cursor=None)	List metrics
create_metric(create_metric_request)	Create a metric
get_metric(name)	Get a metric by name
update_metric(name, update_metric_request)	Partial update (today: display_name)

Plans (codelet.plans)

Method	Description
list_plans(status="published", page_size=None, cursor=None)	List plans (default: published)
create_plan(create_plan_request)	Create a draft plan
get_plan(plan_id, include_pricing_details=False)	Get a plan
publish_plan(plan_id)	Publish the draft version

Subscriptions (codelet.subscriptions)

Method	Description
list_subscriptions(customer=None, status=None, page_size=None, cursor=None)	List subscriptions
get_subscription(subscription_id)	Get a subscription
cancel_subscription(subscription_id, cancel_subscription_request)	Cancel (at_period_end or immediate)
resume_subscription(subscription_id)	Clear a scheduled cancellation

Usage (codelet.usage)

Method	Description
ingest_event(ingest_event_request)	Ingest a usage event (no auto idempotency key)

Request and response models live under codelet.models.

Request and response shapes match the OpenAPI spec. See also codelet.co/SKILL.md for merchant integration guidance.

Errors

from codelet import CodeletError, CodeletRateLimitError

try:
    codelet.ingest({...})
except CodeletRateLimitError:
    # 429
    pass
except CodeletError:
    # other API errors (status + body)
    pass

Generated APIs raise ApiException from the OpenAPI client. The top-level ingest helper maps those to CodeletError / CodeletRateLimitError.

Development

# from repo root
make sdk-generate
cd sdks/python && python3 -m venv .venv && source .venv/bin/activate && pip install -e .

Hand-written surface (src/codelet/) stays stable. Generated code under src/codelet_generated/ is overwritten by make sdk-generate, which also refreshes src/codelet/models.py public re-exports.