Subscriptions & Stripe

A ModuleX subscription is a Stripe-backed plan attached to your organization. It sets the monthly credit allowance and the limits your organization runs against. This page covers the full lifecycle: how a subscription is created through Stripe Checkout, how plan changes and cancellations are scheduled, how ModuleX stays in sync through a signature-verified Stripe webhook, the states a subscription moves through, and the SDK surface.

The subscriptions resource exists in the Python SDK only. The JavaScript SDK has no subscriptions resource and no subscription methods. Wherever a checkout or portal link is needed from code, use the Python SDK or call the REST endpoints directly. See Subscriptions are Python-SDK-only below and the SDK parity matrix.

Who can manage subscriptions

Every /subscriptions/* endpoint is organization-scoped and reserved for owners and admins:

Most endpoints require admin or owner (the organization_admin_required dependency).
POST /subscriptions/wallet/topup requires owner specifically.

The member role is retired: only owners and admins exist. Every request must carry the organization context header. See Org context & X-Organization-ID and Roles & permissions.

string

required

A bearer token: either a mx_live_… API key or a Clerk session token. Example: Authorization: Bearer mx_live_…. See Authentication.

string

required

The UUID of the organization whose subscription you are managing. Missing this header on an org-scoped route returns 400/422.

These endpoints have no global /v1 prefix — each router carries its own. The subscription endpoints live under /subscriptions, and the Stripe webhook lives under /stripe. Trailing-slash redirects are off, so call paths exactly as written. See Base URLs & versioning.

Lifecycle states

A subscription’s status mirrors Stripe verbatim. ModuleX treats the following set as active (entitlements apply): trialing, active, past_due, unpaid. Anything outside that set falls the organization back to the Free plan.

State	What it means	Entitlements
`trialing`	Inside the 7-day trial (Pro/Max only, once per organization).	Plan entitlements apply.
`active`	Paid and current.	Plan entitlements apply.
`past_due`	A renewal payment failed; inside the dunning grace window.	Plan entitlements apply until the grace window closes, then operations are suspended.
`unpaid`	Payment unresolved after dunning.	In the active set, but `operations_suspended` is set — the usage gate denies managed work with a `402`.
`canceled` / other	Not in the active set.	Organization falls back to Free.

operations_suspended is the flag that gates a paying-but-unpaid organization. It is set when status is unpaid, or when status is past_due and the failed-payment grace window (anchored on the first failure, plus 3 days) has passed. A suspended organization’s managed runs return a credit_exhausted 402 from the gate and do not fall back to the Free tier. Restoring payment clears the flag — see Trials & dunning.

Creating a subscription — Stripe Checkout

A new subscription starts with a Stripe Checkout session in subscription mode. ModuleX returns a hosted checkout URL; you redirect the owner or admin to it, and the subscription is created by Stripe and mirrored back through the webhook.

`POST /subscriptions/checkout-link`

Creates a Stripe Checkout session (mode=subscription) for a plan and billing interval. Requires admin or owner.

The plan, interval, and legacy plan id are sent as query parameters, not a JSON body. The Python SDK’s checkout_link() does the same — it passes params, not json.

string

required

The billing interval: month or year.

string

The plan to subscribe to: pro or max. Preferred over plan_id. One of plan_slug or plan_id is required.

string

deprecated

A legacy database plan id. Deprecated — use plan_slug.

string

The hosted Stripe Checkout URL. Redirect the user here to complete payment. On completion, Stripe redirects to {FRONTEND_URL}/settings/billing?checkout=success; on abandonment, to ?checkout=canceled.

curl -X POST 'https://api.modulex.dev/subscriptions/checkout-link?interval=month&plan_slug=pro' \
  -H 'Authorization: Bearer mx_live_…' \
  -H 'X-Organization-ID: 7f1c9a2e-3b4d-4e6a-9c12-8a5b6d2f0e11'

import asyncio
from modulex import Modulex


async def main():
    async with Modulex(
        api_key="mx_live_…",
        organization_id="7f1c9a2e-3b4d-4e6a-9c12-8a5b6d2f0e11",
    ) as mx:
        # plan_slug and interval are sent as query parameters.
        link = await mx.subscriptions.checkout_link("pro", "month")
        print(link.url)  # redirect the owner/admin here


asyncio.run(main())

// The JavaScript SDK has NO subscriptions resource.
// Call the REST endpoint directly to create a checkout link.
const res = await fetch(
  "https://api.modulex.dev/subscriptions/checkout-link?interval=month&plan_slug=pro",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer mx_live_…",
      "X-Organization-ID": "7f1c9a2e-3b4d-4e6a-9c12-8a5b6d2f0e11",
    },
  },
);
const { url } = await res.json();
// redirect the owner/admin to `url`

The Stripe price is resolved live by lookup key (for example pro_monthly, max_annual), never a hard-coded id. The checkout quantity is the organization’s active member count (the owner is seat 1). The session stamps subscription_data.metadata = { organization_id, plan_slug } so the webhook can attribute the resulting subscription.

Errors for POST /subscriptions/checkout-link

Status	Condition
`400`	Neither `plan_slug` nor `plan_id` supplied.
`400`	The plan is Enterprise — `"Enterprise plans are sales-led; contact sales."` See Contact sales.
`400`	The plan is inactive — `"This plan is no longer available for purchase"`.
`400`	No Stripe price for the requested interval.
`400`	The organization has no Stripe customer configured.
`404`	`"Subscription plan not found"`.
`500`	The Stripe API key is not configured.
`502`	A Stripe API error occurred (`"Stripe error: …"`).

These are plain {"detail": "…"} (HTTPException) shapes, not the billing DenialEnvelope. See Errors & status codes.

Trials

A 7-day trial is added to the checkout automatically when both conditions hold:

The organization is trial-eligible: it has never trialed and the owner has never subscribed before. ModuleX tracks this with organizations.has_ever_trialed and users.has_ever_subscribed.
The synced Stripe price has trial_period_days > 0.

Trials apply to Pro and Max only. If a trial ends with no payment method on file, the subscription is canceled (trial_settings.end_behavior.missing_payment_method = "cancel"). Full eligibility and grace behavior is on Trials & dunning.

Changing plans — transitions

Once a subscription exists, an admin or owner changes plan or interval through a transition. ModuleX computes the direction (upgrade, downgrade, or no-op) and applies it either immediately or at the period end.

`POST /subscriptions/transition`

Self-serve plan change. Requires admin or owner. Seats are preserved across the change (the quantity is carried over).

string

required

The target plan: pro or max. Enterprise transitions are rejected — Enterprise is sales-led.

string

default:"month"

The target billing interval: month or year.

The response depends on the direction:

string

One of upgrade, downgrade, or noop.

string

immediate for upgrades, period_end for downgrades. Absent on a no-op.

string

ISO 8601 timestamp when a period_end change takes effect (downgrades only).

string

The plan the downgrade will move to (downgrades only).

string

The interval the downgrade will move to (downgrades only).

string

The Stripe SubscriptionSchedule id backing a scheduled downgrade (downgrades only).

string

Present on a no-op: "Already on this plan + interval."

The direction rule is the single source of truth for up- versus down-grade:

From → To	Direction	When it applies
Lower tier → higher tier	Upgrade	Immediately.
Higher tier → lower tier	Downgrade	At the period end.
Same tier, monthly → annual	Upgrade	Immediately.
Same tier, annual → monthly	Downgrade	At the period end.
Same tier, same interval	No-op	Returns the no-op message.

curl -X POST 'https://api.modulex.dev/subscriptions/transition' \
  -H 'Authorization: Bearer mx_live_…' \
  -H 'X-Organization-ID: 7f1c9a2e-3b4d-4e6a-9c12-8a5b6d2f0e11' \
  -H 'Content-Type: application/json' \
  -d '{"plan_slug": "max", "interval": "month"}'

# There is no SDK method for transitions in either SDK — call REST directly.
import asyncio, httpx


async def main():
    async with httpx.AsyncClient() as http:
        res = await http.post(
            "https://api.modulex.dev/subscriptions/transition",
            headers={
                "Authorization": "Bearer mx_live_…",
                "X-Organization-ID": "7f1c9a2e-3b4d-4e6a-9c12-8a5b6d2f0e11",
            },
            json={"plan_slug": "max", "interval": "month"},
        )
        print(res.json())  # e.g. {"action": "upgrade", "effective": "immediate"}


asyncio.run(main())

// No subscriptions resource in the JS SDK — call REST directly.
const res = await fetch("https://api.modulex.dev/subscriptions/transition", {
  method: "POST",
  headers: {
    Authorization: "Bearer mx_live_…",
    "X-Organization-ID": "7f1c9a2e-3b4d-4e6a-9c12-8a5b6d2f0e11",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ plan_slug: "max", interval: "month" }),
});
console.log(await res.json());

Upgrades modify the Stripe subscription immediately with proration_behavior="always_invoice" and payment_behavior="error_if_incomplete", under a per-organization advisory lock. If the card is declined, the change is rejected with a 402 upgrade_payment_failed DenialEnvelope (see below). After an upgrade, the entitlement cache is busted so the new plan takes effect at once.Downgrades (and annual → monthly) are applied as a two-phase Stripe SubscriptionSchedule. The organization keeps its current, higher entitlements until the period-end webhook fires — the entitlement cache is not busted on a downgrade. The pending change is mirrored in pending_plan_slug, pending_interval, and pending_effective_at.

Errors for POST /subscriptions/transition

Status	Condition
`400`	`plan_slug` is missing — `"plan_slug is required"`.
`400`	Target is Enterprise — `"Enterprise plans are sales-led; contact sales."`
`400`	No active subscription — `"No active subscription to transition; start a checkout first."`
`400`	`"Target plan price not available"`.
`402`	Upgrade payment failed (card declined) — flat `DenialEnvelope` with `code: "upgrade_payment_failed"`.
`404`	`"Plan not found"`.
`500`	The Stripe API key is not configured.
`502`	`"Plan transition failed at the billing provider"`.

`POST /subscriptions/transition/cancel`

Undoes a pending downgrade or a pending cancellation — whether it was scheduled from the app or from the Stripe customer portal. Requires admin or owner. It is idempotent: when nothing is pending it returns a no-op without error. ModuleX detects a pending state from pending_plan_slug (a scheduled downgrade) or from cancel_at_period_end / cancel_at / stripe_schedule_id (a scheduled cancel), releases the Stripe schedule and/or resumes the subscription, and clears the pending mirror columns. Because the current tier is never lost in this operation, the entitlement cache is not busted.

boolean

true when a pending change was undone; false on a no-op.

string

Present on a no-op explaining that nothing was pending.

cURL

curl -X POST 'https://api.modulex.dev/subscriptions/transition/cancel' \
  -H 'Authorization: Bearer mx_live_…' \
  -H 'X-Organization-ID: 7f1c9a2e-3b4d-4e6a-9c12-8a5b6d2f0e11'

The customer portal

The Stripe Billing Portal is where owners and admins update payment methods, view invoices, and cancel a subscription. ModuleX returns a one-time portal URL.

`POST /subscriptions/customer-portal`

Creates a Stripe Billing Portal session. Requires admin or owner. Returns to {FRONTEND_URL}/?org_settings=settings/billing when the user is done.

string

The hosted Stripe customer portal URL. Redirect the user here.

curl -X POST 'https://api.modulex.dev/subscriptions/customer-portal' \
  -H 'Authorization: Bearer mx_live_…' \
  -H 'X-Organization-ID: 7f1c9a2e-3b4d-4e6a-9c12-8a5b6d2f0e11'

import asyncio
from modulex import Modulex


async def main():
    async with Modulex(
        api_key="mx_live_…",
        organization_id="7f1c9a2e-3b4d-4e6a-9c12-8a5b6d2f0e11",
    ) as mx:
        portal = await mx.subscriptions.customer_portal()
        print(portal.url)  # redirect the owner/admin here


asyncio.run(main())

// No subscriptions resource in the JS SDK — call REST directly.
const res = await fetch(
  "https://api.modulex.dev/subscriptions/customer-portal",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer mx_live_…",
      "X-Organization-ID": "7f1c9a2e-3b4d-4e6a-9c12-8a5b6d2f0e11",
    },
  },
);
const { url } = await res.json();

A cancellation made in the Stripe portal arrives back in ModuleX as a scheduled period-end cancel. You can undo it with POST /subscriptions/transition/cancel while it is still pending.

Errors for POST /subscriptions/customer-portal

Status	Condition
`400`	The organization has no Stripe customer configured.
`404`	`"Organization not found"`.
`500`	The Stripe API key is not configured.
`502`	A Stripe API error occurred (`"Stripe error: …"`).

Reading subscription state

Two read endpoints expose the current plan and the catalog. Both are the read methods the Python SDK wraps.

`GET /subscriptions/organization-billing`

Returns the organization’s current subscription, its plan, and any scheduled change or cancellation. Requires admin or owner.

boolean

false when the organization has no active subscription (on Free). Then subscription and plan are null.

object

The active subscription, or null.

Show subscription

string

One of the lifecycle states: trialing, active, past_due, unpaid, etc.

string

ISO 8601 timestamp.

string

ISO 8601 timestamp — the renewal date.

string

month or year.

number

The subscription price in dollars.

integer

Seat count (active members).

object

A pending period-end plan/interval change, or null: { plan_slug, interval, effective_at }.

boolean

object

A pending cancellation, or null: { cancel_at_period_end, effective_at }.

string

ISO 8601 timestamp.

object

The plan backing the subscription, or null.

Show plan

string

For example Pro.

string

For example pro.

integer

boolean

array

Price entries. In this billing object each entry uses the field name price (see the field-name note below): { interval, price, currency }.

array

Feature labels for the plan.

curl 'https://api.modulex.dev/subscriptions/organization-billing' \
  -H 'Authorization: Bearer mx_live_…' \
  -H 'X-Organization-ID: 7f1c9a2e-3b4d-4e6a-9c12-8a5b6d2f0e11'

import asyncio
from modulex import Modulex


async def main():
    async with Modulex(
        api_key="mx_live_…",
        organization_id="7f1c9a2e-3b4d-4e6a-9c12-8a5b6d2f0e11",
    ) as mx:
        billing = await mx.subscriptions.organization_billing()
        if billing.has_subscription:
            sub = billing.subscription
            print(sub.status, sub.billing_interval, sub.current_period_end)


asyncio.run(main())

// No subscriptions resource in the JS SDK — call REST directly.
const res = await fetch(
  "https://api.modulex.dev/subscriptions/organization-billing",
  {
    headers: {
      Authorization: "Bearer mx_live_…",
      "X-Organization-ID": "7f1c9a2e-3b4d-4e6a-9c12-8a5b6d2f0e11",
    },
  },
);
const billing = await res.json();

Example response (active subscription)

{
  "has_subscription": true,
  "subscription": {
    "id": "sub_1QabcDEfghIJklmn",
    "status": "active",
    "current_period_start": "2026-06-01T00:00:00+00:00",
    "current_period_end": "2026-07-01T00:00:00+00:00",
    "billing_interval": "month",
    "current_price": 25.0,
    "quantity": 3,
    "scheduled_change": null,
    "cancel_at_period_end": false,
    "scheduled_cancel": null,
    "created_at": "2026-05-01T09:12:44+00:00"
  },
  "plan": {
    "id": "00000000-0000-0000-0000-0000000000pr",
    "name": "Pro",
    "plan_slug": "pro",
    "sort_order": 0,
    "is_enterprise": false,
    "prices": [{ "interval": "month", "price": 25.0, "currency": "usd" }],
    "features": ["Live team collaboration", "Email support"]
  }
}

`GET /subscriptions/organization-plans`

Lists the available plans with a per-organization relation (whether each plan is the current one, an upgrade, or a downgrade), whether it is selectable, and any discounted price. Requires admin or owner. The Admin plan is never exposed, and no Stripe ids are leaked.

array

The plan catalog.

Show plan item

string

integer

boolean

false for Enterprise.

array

Price entries. In the catalog each entry uses the field name amount (not price): { interval, amount, currency }.

object

Per-interval discounted prices when a coupon applies: { month, year }.

string

An optional display badge.

array

Feature labels.

string

current, upgrade, or downgrade relative to this organization.

integer

The number of plans returned.

curl 'https://api.modulex.dev/subscriptions/organization-plans' \
  -H 'Authorization: Bearer mx_live_…' \
  -H 'X-Organization-ID: 7f1c9a2e-3b4d-4e6a-9c12-8a5b6d2f0e11'

import asyncio
from modulex import Modulex


async def main():
    async with Modulex(
        api_key="mx_live_…",
        organization_id="7f1c9a2e-3b4d-4e6a-9c12-8a5b6d2f0e11",
    ) as mx:
        catalog = await mx.subscriptions.organization_plans()
        for plan in catalog.plans:
            # catalog prices use the `amount` field
            prices = [(p.interval, p.amount) for p in plan.prices]
            print(plan.plan_slug, plan.relation, prices)


asyncio.run(main())

// No subscriptions resource in the JS SDK — call REST directly.
const res = await fetch(
  "https://api.modulex.dev/subscriptions/organization-plans",
  {
    headers: {
      Authorization: "Bearer mx_live_…",
      "X-Organization-ID": "7f1c9a2e-3b4d-4e6a-9c12-8a5b6d2f0e11",
    },
  },
);
const { plans, total } = await res.json();

The price field name differs by endpoint. The catalog (organization-plans) uses amount, while the billing object (organization-billing) uses price. The Python SDK models reflect this: PlanPrice.amount for the catalog versus BillingPlanPrice.price for the billing plan. Read the correct field for the endpoint you called.

Staying in sync — the Stripe webhook

ModuleX does not poll Stripe for state. Stripe pushes events to a single webhook, and ModuleX mirrors the relevant ones into its own subscription, wallet, and catalog tables. The webhook is the source of every status change you observe through the read endpoints.

`POST /stripe/webhook`

The webhook receiver. It is not authenticated with a bearer token — it verifies a Stripe signature instead. It is idempotent, order-aware, and retryable.

string

required

The Stripe signature header. ModuleX verifies it against STRIPE_WEBHOOK_SECRET using the raw request body. Verification or parse failure returns 400 "Invalid webhook signature" with no error detail leaked. A missing STRIPE_WEBHOOK_SECRET returns 500.

This endpoint is a Stripe-to-server receiver, not a client call. Neither SDK exposes it, and you should never call it yourself — you configure its URL in your Stripe dashboard. See the SDK parity matrix for the full list of routes with no SDK method.

Handled events

Each delivered event is normalized once and dispatched by type. A redelivered event that was already processed short-circuits to { "received": true, "duplicate": true }.

Event type	Effect
`customer.subscription.created` / `.updated` / `.deleted`	Watermarked mirror upsert of the subscription.
`invoice.payment_failed` / `invoice.payment_action_required`	Dunning: anchor the grace window and schedule a suspend job.
`invoice.paid` / `invoice.payment_succeeded`	Restore: clear the dunning anchor and any suspension. No fresh credit grant.
`subscription_schedule.*`	Re-mirror the linked subscription and persist a portal-scheduled cancel.
`payment_intent.succeeded`	Apply a wallet top-up credit (idempotent on the payment-intent id).
`charge.refunded`	Apply a wallet refund (idempotent on the charge id). Never touches subscription status.
`product.` / `price.` / `coupon.` / `promotion_code.`	Re-sync the catalog mirror (best-effort).
`checkout.session.completed` / `customer.subscription.trial_will_end`	Logged and acknowledged; the business effect is handled elsewhere.
Unknown	Acknowledged and ignored: `{ "received": true, "ignored": true, "type": … }`.

Stripe emits customer.subscription.deleted for a cancellation — there is no customer.subscription.canceled event. If you wire up your own listeners against Stripe, handle .deleted.

A customer.subscription.deleted event mirrors the subscription’s terminal status; the organization then falls to Free because the deleted status is outside the active set. A restored payment after dunning clears suspension but does not re-grant credits or reset the monthly bucket — this is deliberate, to prevent farming a fresh allowance by lapsing and recovering. See Trials & dunning and Credits & metering.

Retries and dead-lettering

The webhook answers Stripe so that genuinely transient failures are retried and permanent ones are not:

Transient failure under the cap

An organization-not-found race (the customer-create event arrives before the org commit), or a database or Stripe error mid-processing, returns 503 so Stripe retries — up to WEBHOOK_TRANSIENT_RETRY_CAP (default 5) attempts.

Transient failure at the cap

Once the retry cap is reached, the event is dead-lettered, marked processed, and acknowledged with 200 so Stripe stops retrying: { "received": true, "dead_lettered": true, … }.

Permanent failure

A malformed payload (for example a missing customer) raises a permanent error: the event is dead-lettered, marked processed, and acknowledged with 200. No retry.

Success

The event is recorded for deduplication and acknowledged with 200: { "received": true, "type": … }.

Ordering. Subscription mirror upserts carry a watermark on the event’s created timestamp. A stale (older) event that arrives after a newer one is rejected without corrupting the newer state, so out-of-order delivery from Stripe cannot roll your subscription back.

Subscriptions are Python-SDK-only

The subscriptions resource is part of the Python SDK only. The JavaScript SDK has no subscriptions resource and exposes no subscription methods — confirmed against the SDK parity matrix. From JavaScript, call the REST endpoints directly (as shown in the JavaScript tabs above) or surface billing through the app’s customer portal. The Python SDK wraps four of the subscription endpoints:

Python method	REST endpoint	Notes
`client.subscriptions.organization_plans()`	`GET /subscriptions/organization-plans`	Catalog with per-org `relation`. Prices use `amount`.
`client.subscriptions.organization_billing()`	`GET /subscriptions/organization-billing`	Current subscription + plan. Plan prices use `price`.
`client.subscriptions.checkout_link(plan_slug, interval, *, plan_id=None)`	`POST /subscriptions/checkout-link`	Params sent as query, not body.
`client.subscriptions.customer_portal()`	`POST /subscriptions/customer-portal`	Returns a portal URL.

The remaining /subscriptions/* endpoints have no SDK method in either SDK and must be called over REST:

GET /subscriptions/wallet
PATCH /subscriptions/wallet/extra-usage
POST /subscriptions/wallet/topup
POST /subscriptions/transition
POST /subscriptions/transition/cancel

The wallet endpoints are documented on Wallet & top-ups; the transition endpoints are above on this page.

Every method accepts a per-call organization_id that overrides the client default. All four methods are async and require an owner or admin token. The full method-to-route mapping, including the cross-SDK gaps, is on the SDK parity matrix; installation and configuration are on the Python SDK page.

Error shapes you may see

Subscription endpoints can return two different 402 shapes, and you must branch on both:

{
  "code": "upgrade_payment_failed",
  "layer": "credit",
  "key": "7f1c9a2e-3b4d-4e6a-9c12-8a5b6d2f0e11",
  "current": null,
  "limit": 5000.0,
  "reason": "upgrade_payment_failed"
}

{
  "detail": { "reason": "paid_subscription_required" }
}

The flat DenialEnvelope ({ code, layer, key, current, limit, reason }) comes from the billing gate — for example an upgrade whose card was declined returns code: "upgrade_payment_failed". This is the same envelope the usage gate raises for 402 / 403 / 429.
The HTTPException shape ({"detail": {…}}) comes from the wallet paid-plan checks (PATCH /subscriptions/wallet/extra-usage, POST /subscriptions/wallet/topup), which return {"detail": {"reason": "paid_subscription_required"}} when an organization without a paid subscription tries to use a paid-only feature.

The other subscription errors (400, 404, 500, 502) use the plain {"detail": "…"} string shape. All three envelope shapes are catalogued on Errors & status codes.

In the Python SDK, a 402 raises PaymentRequiredError and, when the body carries a recognized billing layer, a more specific subclass (CreditExhaustedError, WalletError, or QuotaExceededError). A 403 raises PermissionError and a 429 raises RateLimitError. See Errors & retries.

Configuration reference

These environment variables govern the Stripe integration on the server. They are listed here so you understand the behavior; you set them on the deployment, not through the API.

Variable	Default	Controls
`STRIPE_API_KEY`	`""`	Stripe secret key. Missing → `500` on any Stripe call.
`STRIPE_WEBHOOK_SECRET`	`""`	Webhook signature secret. Missing → `500` on the webhook.
`FRONTEND_URL`	`http://localhost:3000`	Base for the checkout success/cancel and portal return URLs.
`WEBHOOK_TRANSIENT_RETRY_CAP`	`5`	Transient retries before an event is dead-lettered.

The wallet top-up bounds (WALLET_TOPUP_MIN_USD = 10, WALLET_TOPUP_MAX_USD = 1000), the credit conversion rate ($0.01 per credit), and auto top-up defaults live with the wallet and credits configuration rather than the subscription surface.

Plans & pricing

Free, Pro, Max, and Enterprise — allowances, limits, and both annual prices.

Wallet & top-ups

The prepaid wallet, the top-up checkout, and auto top-up.

Trials & dunning

Trial eligibility, grace periods, suspension, and recovery.

Usage gating & limits

The admission gate and its 402, 403, and 429 responses.

Python SDK

Install and configure the async client that exposes the subscriptions resource.

SDK parity matrix

Which routes each SDK covers — and where the gaps are.

Billing & credits

Data & limits

Guides

Power using

Subscriptions & Stripe

Who can manage subscriptions

Lifecycle states

Creating a subscription — Stripe Checkout

`POST /subscriptions/checkout-link`

Trials

Changing plans — transitions

`POST /subscriptions/transition`

`POST /subscriptions/transition/cancel`

The customer portal

`POST /subscriptions/customer-portal`

Reading subscription state

`GET /subscriptions/organization-billing`

`GET /subscriptions/organization-plans`

Staying in sync — the Stripe webhook

`POST /stripe/webhook`

Handled events

Retries and dead-lettering

Subscriptions are Python-SDK-only

Error shapes you may see

Configuration reference

Plans & pricing

Wallet & top-ups

Trials & dunning

Usage gating & limits

Python SDK

SDK parity matrix

​Who can manage subscriptions

​Lifecycle states

​Creating a subscription — Stripe Checkout

​POST /subscriptions/checkout-link

​Trials

​Changing plans — transitions

​POST /subscriptions/transition

​POST /subscriptions/transition/cancel

​The customer portal

​POST /subscriptions/customer-portal

​Reading subscription state

​GET /subscriptions/organization-billing

​GET /subscriptions/organization-plans

​Staying in sync — the Stripe webhook

​POST /stripe/webhook

​Handled events

​Retries and dead-lettering

​Subscriptions are Python-SDK-only

​Error shapes you may see

​Configuration reference

​Related pages

Plans & pricing

Wallet & top-ups

Trials & dunning

Usage gating & limits

Python SDK

SDK parity matrix

Who can manage subscriptions

Lifecycle states

Creating a subscription — Stripe Checkout

`POST /subscriptions/checkout-link`

Trials

Changing plans — transitions

`POST /subscriptions/transition`

`POST /subscriptions/transition/cancel`

The customer portal

`POST /subscriptions/customer-portal`

Reading subscription state

`GET /subscriptions/organization-billing`

`GET /subscriptions/organization-plans`

Staying in sync — the Stripe webhook

`POST /stripe/webhook`

Handled events

Retries and dead-lettering

Subscriptions are Python-SDK-only

Error shapes you may see

Configuration reference

Related pages