The model
Enumerations
BillingCycle also answers two questions the rest of the system asks: whether the cycle recurs, and whether it renews.
What a plan grants
PlanConfig is the capability side of a plan: per-feature settings for chat, writer, imagine, video, transcription, voice-over, voice isolation and classification, plus allowed models, tool switches, allowed assistants and templates, and an extensions map plugins can add to.
Because a snapshot carries the config, a subscription keeps the capabilities it was sold with. See Plan config extensions.
Credits
Credits live on the workspace, in three places:
A
null credit count means unlimited. Deduction takes from the subscription first, then the add-on balance.
BillingService is the gate everything goes through:
Relevant options:
option.billing.usage_mode, which is either unpaced or session-based, and option.billing.negative_balance_enabled.
Purchase flow
1
Order
Creating an order snapshots the plan, applies a coupon, and asks the configured tax engine for tax lines.
2
Payment
The selected gateway starts the payment, and the user is redirected or shown an embedded form.
3
Confirmation
On return, the gateway verifies the payment and hands back a provider reference. The order is paid.
4
Fulfilment
For a recurring plan, a subscription is created from the order, carrying the reference and the gateway. For a one-time plan, credits are added to the workspace. Any previous subscription is cancelled.
Renewals
A cron listener renews subscriptions that are due, in batches, tracking its position in an option. Renewal resets usage, settles any credit debt, and moves the next reset 30 days out, then dispatches a usage reset event. Cancelling sets the subscription to end at its next renewal date and asks the gateway to cancel at the provider. A second cron listener ends expired subscriptions, moving the workspace to the plan configured asoption.billing.fallback_plan.
Payment gateways
Gateways are registered in a factory, keyed by a lookup key, and implement a small interface for purchase, completion, cancellation and webhooks. Marker interfaces describe how the gateway is presented and whether it supports a given plan. Aikeedo ships Stripe, PayPal, bank transfer and manual payment.Tax
A tax engine calculates lines when an order is created, and the result is stored on the order, so gateways charge the taxed total without extra work. The selected engine comes fromoption.billing.tax_engine, falling back to a no-op engine. See Tax engines.