Billing: plans, subscriptions, invoices, coupons, usage and feature entitlements.
None of the money logic lives here. It delegates to the ledger engine
(github.com/xraph/ledger) and spends its own effort on the part that touches auth: hooking
lifecycle events so a new organisation gets a trial without anyone clicking anything, and
answering the entitlement question your feature flags need.
You choose whether a tenant is an organisation or a user, which decides who the invoice belongs to.
- You are charging for the product and want subscription state next to identity, not in a separate system
- Feature gating depends on plan, so your code needs to ask "is this tenant entitled to X"
- New signups should land on a trial automatically
- You are not charging yet. This is a lot of surface area to carry for revenue you do not have
- Your billing already lives in Stripe and you are happy querying it there
- You have not wired the ledger engine. The plugin has nothing to delegate to without it
authsome.WithPlugin(subscription.New(subscription.Config{
DefaultPlanSlug: "starter",
AutoSubscribeOnOrg: true,
TrialDays: 14,
})),| Field | Type | Default | What it does |
|---|---|---|---|
PathPrefix |
string |
/v1/billing |
Where billing routes are mounted |
DefaultPlanSlug |
string |
empty | Plan auto-assigned to a new tenant |
AutoSubscribeOnOrg |
bool |
false |
Subscribe on org creation, in organisation mode |
AutoSubscribeOnUser |
bool |
false |
Subscribe on signup, in user mode |
TrialDays |
int |
0 |
Trial length for auto-subscribed tenants. 0 means no trial. Subscriptions created through the API take the plan's own trial_days |
Checkout |
CheckoutProvider |
nil |
Takes payment before a tenant moves onto a paid plan. See Taking payment |
AllowSelfService |
bool |
false |
Deprecated and unused. Self-service is the subscription.self_service_upgrade setting |
DisableRoutes |
bool |
false |
Mount no HTTP routes. Set it when you serve your own billing API on top of the plugin's ledger |
DisableAutoSubscribe |
bool |
false |
Turn off the org-create and signup hooks, whatever the settings say. Set it when you create subscriptions yourself |
| Key | Default |
|---|---|
subscription.default_plan |
empty |
subscription.tenant_mode |
organization |
subscription.auto_subscribe_org |
true |
subscription.auto_subscribe_user |
false |
subscription.trial_days |
14 |
subscription.self_service_upgrade |
true |
subscription.billing_roles |
["owner"] |
subscription.grace_period_days |
3 |
billing_roles can be set per app and per organization, so an organization can let its
admins manage billing without changing it for everyone else.
These are the routes your app's own UI calls. They work on the caller's tenant, so you never pass a subscription ID, and you don't have to pass a tenant either: in organization mode it's the session's active organization, in user mode it's the user.
| Method | Path | Purpose |
|---|---|---|
GET |
/subscription |
Your subscription (with its plan), or null, plus can_manage |
POST |
/subscription |
Subscribe. Body: plan (slug or ID), optional seats |
PATCH |
/subscription |
Change plan, seats, or both |
POST |
/subscription/cancel |
Cancel at the period end, or now with {"when":"now"} |
POST |
/subscription/resume |
Take back a cancellation scheduled for the period end |
GET |
/entitlements |
Every feature on your plan, checked in one call |
POST |
/portal |
A billing portal URL, when your checkout provider has one |
Anyone in the organization can read. To write you need self-service on
(subscription.self_service_upgrade) and a role listed in subscription.billing_roles,
which is just owner out of the box. GET /subscription tells you which with
can_manage, so you can hide the upgrade button from people who'd get a 403.
Writes answer with the updated subscription, so you don't need to fetch it again:
{
"subscription": {
"id": "sub_...",
"status": "active",
"plan": { "slug": "team", "name": "Team", "amount_minor": 4900, "features": [] },
"current_period_end": "2026-12-10T09:30:00Z",
"cancel_at": null,
"seats": { "feature_key": "seats", "used": 3, "limit": 10 }
}
}A cancellation at the period end leaves status at active and sets cancel_at. That's
your cue to show "ends on" and a button that calls /subscription/resume. A subscription
that's past_due or paused still counts as the tenant's subscription: GET shows it, and
subscribing again answers 409.
Pausing is still an operator action, through the ID routes below. A tenant can't unpause itself or change the plan of a paused subscription, because a pause is often how you stop service for an unpaid invoice. Agents and other delegated sessions can read but not write.
Without a checkout provider, subscribing grants the plan straight away. That's fine for free
plans and trials. To charge, give the plugin a CheckoutProvider. Every subscribe and every
plan or seat change asks it first: return a URL to send the customer to your payment page, or
an empty result when there's nothing to pay and the change should just happen.
func (s stripeCheckout) Checkout(ctx context.Context, req subscription.CheckoutRequest) (subscription.CheckoutResult, error) {
// req.Plan is where they're going, req.CurrentPlan where they are.
// Return CheckoutResult{} to apply now, or CheckoutResult{URL: ...} to charge first.
}
authsome.WithPlugin(subscription.New(subscription.Config{
Checkout: stripeCheckout{},
}))When you return a URL the API answers {"checkout_url": "..."} and changes nothing. Once
your payment provider's webhook says they paid, call plugin.CompleteCheckout(ctx, req). It's
safe to call twice for one payment and records the same audit entry and event as the API.
Cancel and resume never go through the provider. Listen for subscription.canceled,
subscription.plan_changed and subscription.resumed and update your provider to match, or a
customer who cancels in your app keeps getting charged.
If your provider also implements PortalProvider, POST /portal returns a link to its
hosted page for payment details and invoices. Without one that route answers 404.
A provider error is logged and the client gets a 502, so nothing from your payment provider's error text reaches the browser.
Two subscribes for one tenant at the same moment are serialized within a process, not across replicas, because ledger has no per-tenant uniqueness yet.
Mounted under PathPrefix, /v1/billing by default. The self-service routes are above;
these are the rest, mostly for operators.
| Method | Path | Purpose |
|---|---|---|
GET |
/plans |
List plans you can buy: active base plans, cheapest first. Operators can pass status=all, and anyone can pass include_addons=true |
POST |
/plans |
Create a plan |
GET |
/plans/:planId |
Read a plan |
POST |
/plans/:planId/activate |
Activate a plan |
POST |
/plans/:planId/archive |
Archive a plan |
GET |
/subscriptions |
List subscriptions |
POST |
/subscriptions |
Create a subscription |
GET |
/subscriptions/active |
Read the active subscription |
POST |
/subscriptions/:subId/change-plan |
Move to another plan |
POST |
/subscriptions/:subId/pause |
Pause |
POST |
/subscriptions/:subId/resume |
Resume |
POST |
/subscriptions/:subId/cancel |
Cancel |
GET |
/invoices |
List invoices |
GET |
/invoices/:invoiceId |
Read an invoice |
POST |
/invoices/:invoiceId/pay |
Mark paid |
POST |
/invoices/:invoiceId/void |
Void |
GET |
/entitlements/:featureKey |
Check a feature entitlement |
GET |
/usage |
Usage summary |
GET |
/coupons |
List coupons |
POST |
/coupons |
Create a coupon |
DELETE |
/coupons/:couponId |
Delete a coupon |
Subscription, invoice, entitlement and usage reads on these routes are scoped to a tenant:
pass its tenant_id. (The self-service routes above fill it in from the session instead.)
You can read a tenant you belong to (organisation mode) or are (user mode).
Anyone else gets a 404, whether the tenant exists or not, unless they hold
billing:manage, which reads every tenant. Plans stay app-wide.
The ID routes answer a transition the ledger refuses (changing or resuming a canceled
subscription, say) with a 409. You need
billing:manage for GET /coupons and for the dashboard billing views as well, because
both list data from the whole app. One caveat: on an engine with no RBAC, the coupon list
and the write routes only ask for a session, since there is no permission to check. The
tenant reads go the other way and treat a missing RBAC as not holding billing:manage.
billing:manage doesn't cross apps. When your request is scoped to an app (an API key
or an app-bound session), every billing route stays inside it. An app_id naming another
app gets a 404, and so does a subscription, invoice, coupon or plan from another app
addressed by ID. Leave app_id off and the route uses your request's app.
To run your own billing API, set DisableRoutes and call plugin.Service() from your
handlers. Pass your ledger to authsome.WithLedgerEngine and the plugin picks it up
when the engine starts, so you can skip RebindLedgerOnPlugins. If you build the ledger
after the engine and hand it over with SetLedgerEngine, you still need to call it.
| Hook | What happens |
|---|---|
AfterOrgCreate |
Auto-subscribes the new organisation, in organisation mode |
AfterSignUp |
Auto-subscribes the new user, in user mode |
AfterMemberAdd |
Records seat usage against the ledger, as authsome.orgs.members |
organization supplies the tenant in organisation mode. Entitlement checks pair well with
whatever feature flagging you already run.