Skip to main content

​
The three SDKs

Recurso ships three official SDKs. Each is a typed client over the same REST API, so they cover the same surface — plans, customers, the subscription lifecycle, invoices, the usage platform, wallets, quotes, entitlements, webhooks, analytics, and more — but each follows its language’s own idiom, not a lowest-common-denominator API.
Because the Python client is generated from the OpenAPI spec, its shape differs from Node/Go (per-operation functions and model classes, not resource objects). Follow the Python guide for its idiom rather than translating the Node examples literally.

​
Pick your path

Node.js

Install, configure, and integrate with the TypeScript client.

Go

Services, params structs, and context-aware calls.

Python

The generated client, models, and sync/async calls.

​
Workflows

Task-oriented, end-to-end walkthroughs with side-by-side code in all three languages:

Bill a customer

Customer → plan → subscription → first invoice.

Usage-based billing

Metric → plan charges → record usage → query and rate it.

Subscription changes

Upgrade/downgrade with proration, pause, resume, cancel.

Webhooks

Register endpoints, track deliveries, and redeliver.

Errors & retries

Error handling, idempotency, retries, and pagination.

​
Concepts that apply to every SDK

All three send your API key as a bearer token (Authorization: Bearer <key>). Create and rotate keys in the dashboard under Developers. Use a test key against a test/make demo stack and a live key in production. Never ship a secret key to a browser or mobile client.
Amounts are integers in the currency’s smallest unit — 2900 is $29.00, and 499900 is ₹4,999.00. This avoids floating-point rounding. Convert for display only.
Point the client at your API host — https://api.recurso.dev, your self-hosted URL, or http://localhost:8080 for a local make demo stack. Each language guide shows exactly where the base URL goes.
List endpoints default to a small page size, so always pass an explicit limit when you need the full set. The paging cursor varies by endpoint and SDK — most take limit plus a page or offset — so follow the exact parameter names in your language guide and in Errors & retries.
Money-moving and ingestion endpoints accept an idempotency/transaction key so a retried request doesn’t double-charge or double-count. The usage ingestion path uses a per-event transaction_id; see the usage workflow.