Python SDK

A generated client

The Recurso Python client (package recurso, version 1.4.0) is generated by openapi-python-client. Its shape is deliberately different from the Node and Go SDKs: there are no resource objects like client.plans.create(...). Instead, every API operation is its own module with plain functions, and every request/response body is a model class.

If you’ve read the Node or Go guides, don’t translate them literally. The generated idiom is operation_module.sync(client=client, body=Model(...)). Follow the shapes on this page.

Install

The client isn’t on PyPI yet. Install it from a checkout of the recurso-python repo (which sits beside the other Recurso repos):

pip install ./recurso-python

Requires Python 3.11+. The only runtime dependencies are httpx and attrs.

Construct a client

There are two client classes in the top-level recurso package. Use AuthenticatedClient for the API (every endpoint requires a key); Client is the unauthenticated variant.

from recurso import AuthenticatedClient

client = AuthenticatedClient(
    base_url="https://api.recurso.dev",
    token="sk_...",
)

base_url and token are the two arguments you need. Under the hood the client sends Authorization: Bearer <token> (the prefix defaults to "Bearer" and auth_header_name to "Authorization"). Point base_url wherever your API runs:

Recurso cloud: https://api.recurso.dev
Self-hosted: your own host, e.g. https://billing.internal.example.com
Local make demo stack: http://localhost:8080

The client is also a context manager, which reuses one underlying HTTP connection pool for a batch of calls:

with client as client:
    ...  # make several calls here

The generated idiom

Each path + method becomes a module under recurso.api.<tag>. Import the module (not a symbol from it) and call one of its four functions. Request bodies are model classes under recurso.models.

from recurso.api.plans import create_plan
from recurso.models import CreatePlanRequest, CreatePlanRequestIntervalUnit

plan = create_plan.sync(
    client=client,
    body=CreatePlanRequest(
        name="Gold Monthly",
        code="gold-monthly",
        interval_unit=CreatePlanRequestIntervalUnit.MONTH,
        interval_count=1,
        amount=2900,        # minor units — 2900 = $29.00
        currency="USD",
    ),
)

Every operation module exposes four functions with the same arguments:

Function	Blocking?	Returns
`sync`	yes	the parsed body, or `None`
`sync_detailed`	yes	a `Response[...]` with `.status_code`, `.parsed`, `.content`, `.headers`
`asyncio`	no (`await`)	the parsed body, or `None`
`asyncio_detailed`	no (`await`)	a `Response[...]`

Notes that trip people up:

client is always a keyword argument (client=client).
The request body is passed as body=...; path parameters like an id are positional (e.g. get_plan.sync(plan_id, client=client)).
Model classes are re-exported from recurso.models, so from recurso.models import CreatePlanRequest works. Enum fields have their own classes (e.g. CreatePlanRequestIntervalUnit.MONTH).
Optional fields default to UNSET (from recurso.types) — omit them and they aren’t sent.
Amounts are integers in the currency’s minor unit (2900 = $29.00).

End-to-end example

Create a plan, a customer, and a subscription, then read the plan back and list plans. IDs returned on models are uuid.UUID values and can be passed straight into the next request.

Create a plan

from recurso.api.plans import create_plan
from recurso.models import CreatePlanRequest, CreatePlanRequestIntervalUnit

plan = create_plan.sync(
    client=client,
    body=CreatePlanRequest(
        name="Gold Monthly",
        code="gold-monthly",
        interval_unit=CreatePlanRequestIntervalUnit.MONTH,
        interval_count=1,
        amount=2900,
        currency="USD",
    ),
)
# plan is a recurso.models.Plan; plan.id is a UUID

Create a customer

from recurso.api.customers import create_customer
from recurso.models import CreateCustomerRequest

customer = create_customer.sync(
    client=client,
    body=CreateCustomerRequest(
        email="ada@example.com",
        name="Ada Lovelace",
    ),
)

Create a subscription

customer_id and plan_id take UUID values — pass the IDs from the models you just created.

from recurso.api.subscriptions import create_subscription
from recurso.models import CreateSubscriptionRequest

subscription = create_subscription.sync(
    client=client,
    body=CreateSubscriptionRequest(
        customer_id=customer.id,
        plan_id=plan.id,
    ),
)
# Creates the subscription and generates the first invoice.

Read the plan back

Path parameters are positional. The single-resource GET wraps the object in a response envelope whose payload is on .data.

from recurso.api.plans import get_plan

fetched = get_plan.sync(plan.id, client=client)
print(fetched.data.name)   # GetPlanResponse200 -> .data is a Plan

List plans

List operations take q, limit, and a 1-based page. The results live on .data.

from recurso.api.plans import list_plans

page = list_plans.sync(client=client, limit=50, page=1)
for p in page.data:
    print(p.code, p.amount)

Error handling

The client sets raise_on_unexpected_status=True (a deliberate deviation from the generator’s default), so the two failure modes are:

Documented non-2xx statuses (e.g. 400, 401, 404) do not raise. They parse into an Error model, so sync returns a union — for example Plan | Error | None. Guard with isinstance:

from recurso.models import Error

result = create_plan.sync(client=client, body=body)
if isinstance(result, Error):
    print(result.error.code, result.error.message)  # ErrorError: .code, .message
else:
    plan = result  # a Plan

Undocumented statuses raise recurso.errors.UnexpectedStatus, which carries .status_code and .content:

from recurso.errors import UnexpectedStatus

try:
    plan = create_plan.sync(client=client, body=body)
except UnexpectedStatus as e:
    print(e.status_code, e.content)

To branch on the raw status yourself, use sync_detailed and read response.status_code (an http.HTTPStatus); the typed body, if any, is on response.parsed:

resp = create_plan.sync_detailed(client=client, body=body)
if resp.status_code == 201:
    plan = resp.parsed

Network timeouts surface as httpx.TimeoutException.

Pagination

List operations accept limit and a 1-based page (plus an optional q search string); some also take a filter such as status. Page through by incrementing page until a short page comes back:

from recurso.api.subscriptions import list_subscriptions

page = 1
while True:
    result = list_subscriptions.sync(client=client, limit=100, page=page)
    if not result.data:
        break
    for sub in result.data:
        ...
    page += 1

Idempotency

Mutating calls honor the Idempotency-Key header so a retry settles at most once. Attach it with with_headers, which returns a new client:

idem_client = client.with_headers({"Idempotency-Key": "order-1234"})
create_subscription.sync(client=idem_client, body=body)

Async

Every operation has asyncio / asyncio_detailed twins with identical arguments. Use the client as an async context manager:

async with client as client:
    plan = await create_plan.asyncio(client=client, body=body)

Bill a customer

Customer → plan → subscription → first invoice, end to end.

Usage-based billing

Define a metric, record usage, and rate it.

Get Started

By Language

Workflows

A generated client

Install

Construct a client

The generated idiom

End-to-end example

Error handling

Idempotency

Async

Next

Bill a customer

Usage-based billing

​A generated client

​Install

​Construct a client

​The generated idiom

​End-to-end example

​Error handling

​Pagination

​Idempotency

​Async

​Next

Bill a customer

Usage-based billing

A generated client

Install

Construct a client

The generated idiom

End-to-end example

Error handling

Pagination

Idempotency

Async

Next