Billing
The plan a workspace is on, paying for it through Stripe, and what the Team plan unlocks for an organization.
Every workspace has a plan, and pays for it by itself: a personal account and an organization have separate subscriptions. The price of a plan is for the whole workspace, however many members an organization has. The pricing page has the plans, and GET /v1/billing returns each one with its price and limits.
Cards are entered on pages Stripe hosts, never here. These endpoints hand out a link to the right page, and the plan changes when Stripe confirms what the customer did there. They need a signed-in session, and changing the plan needs an owner of the workspace.
| Plan | Who it is for | Bought here |
|---|---|---|
free | Evaluation. Where every workspace starts, and where it returns when a subscription ends. | No payment |
standard | One person who needs higher limits. | Yes |
team | An organization. Higher limits again, and the plan an organization needs before it can have more than one member. | Yes |
enterprise | Private deployment and custom limits, under a contract. | No: contact us |
Members need Team. Anyone can create an organization, but inviting someone into it, and accepting an invitation to it, return 403 plan_required until it is on team or enterprise. If an organization leaves that plan with more than one member, nobody is removed and nothing is deleted, and it becomes read-only until it is back on Team or down to one member: every write is 403 plan_required, for its owners and its API keys as well. Reading, forking, transferring work out, revoking a key, billing and managing members all still work, and going back on Team restores every role as it was.
Cancelling keeps the plan until the end of the period already paid for, then the workspace goes back to free. Anything over the free limits stays and can be read, and new work is refused with 403 quota_exceeded until it is back under them. A payment that fails does not take the plan away at once: it stays, with payment_failed true, while Stripe retries the card.
#The Billing object
What the workspace has, why, and what it could have.
Attributes
Whether plans can be bought through this server. false on a self-hosted Kaimei with no Stripe key.
The plan the workspace has now: free, standard, team or enterprise.
none when there is no subscription. Otherwise Stripe's word for it: active, trialing, past_due, canceled, unpaid, incomplete, incomplete_expired or paused.Whether a subscription made here is paying for the plan.
The plan was set by Kaimei under a contract. It is not bought or changed through these endpoints.
When the next payment is taken.
Set once the subscription has been cancelled: when it stops and the workspace goes back to free.
The last payment did not go through, and Stripe is retrying it.
Whether there is anything for the portal to show.
Whether the caller may change the plan: an owner of the workspace.
Every plan: id, name, description, price {amount, currency, interval} with the amount in the smallest unit of the currency (700 is $7.00) and null for a plan priced by contract, limits, rate_limit_factor (how many times the free plan's hourly rate limits), members (whether an organization on it can have more than one) and purchasable.
{
"object": "billing",
"enabled": true,
"plan": "team",
"status": "active",
"subscribed": true,
"custom": false,
"renews_at": "2026-12-19T09:30:11Z",
"cancels_at": null,
"payment_failed": false,
"has_billing_account": true,
"can_manage": true,
"plans": [
{
"object": "plan",
"id": "free",
"name": "Free",
"description": "Everything you need to upload a model, explain it and watch it in production.",
"price": {
"amount": 0,
"currency": "usd",
"interval": "month"
},
"limits": {
"models": 10,
"api_keys": 5,
"predictions_per_month": 5000,
"explanations_per_month": 500,
"analyses_per_month": 20
},
"rate_limit_factor": 1,
"members": false,
"purchasable": false
},
…,
{
"object": "plan",
"id": "team",
"name": "Team",
"description": "An organization for your whole team, with owner, admin, member and viewer roles and higher limits.",
"price": {
"amount": 2500,
"currency": "usd",
"interval": "month"
},
"limits": {
"models": 100,
"api_keys": 50,
"predictions_per_month": 200000,
"explanations_per_month": 20000,
"analyses_per_month": 500
},
"rate_limit_factor": 10,
"members": true,
"purchasable": true
},
…
]
}#Retrieve billing
/v1/billingSession token onlyThe plan of the workspace the session acts in, the state of its subscription, and every plan with its price and limits. Any member can read it.
Returns
curl https://api.kaimei.ai/v1/billing \
-H "Authorization: Bearer $SESSION_TOKEN"{
"object": "billing",
"enabled": true,
"plan": "team",
"status": "active",
"subscribed": true,
"custom": false,
"renews_at": "2026-12-19T09:30:11Z",
"cancels_at": null,
"payment_failed": false,
"has_billing_account": true,
"can_manage": true,
"plans": [
{
"object": "plan",
"id": "free",
"name": "Free",
"description": "Everything you need to upload a model, explain it and watch it in production.",
"price": {
"amount": 0,
"currency": "usd",
"interval": "month"
},
"limits": {
"models": 10,
"api_keys": 5,
"predictions_per_month": 5000,
"explanations_per_month": 500,
"analyses_per_month": 20
},
"rate_limit_factor": 1,
"members": false,
"purchasable": false
},
…,
{
"object": "plan",
"id": "team",
"name": "Team",
"description": "An organization for your whole team, with owner, admin, member and viewer roles and higher limits.",
"price": {
"amount": 2500,
"currency": "usd",
"interval": "month"
},
"limits": {
"models": 100,
"api_keys": 50,
"predictions_per_month": 200000,
"explanations_per_month": 20000,
"analyses_per_month": 500
},
"rate_limit_factor": 10,
"members": true,
"purchasable": true
},
…
]
}#Start paying for a plan, or change plan
/v1/billing/checkoutOwner session onlyA link to the Stripe page that puts the workspace on plan. Send the browser to url. A workspace with no subscription gets Stripe Checkout (kind checkout). One that already pays gets the portal page that confirms the change and shows what it costs (kind portal), so a workspace never has two subscriptions. Moving up charges the difference for the rest of the period at once; moving down leaves a credit for the next bill. Nothing changes here until Stripe confirms it. Stripe then returns the browser to the dashboard's billing settings. Asking again closes the Checkout page handed out before, so only the latest one can be paid. Owners only (403 owner_required). 409 already_on_plan when it is on that plan, 409 custom_plan when Kaimei set its plan, 409 subscription_unsettled when a subscription is waiting on a payment (settle or cancel it in the portal), 503 billing_not_configured or plan_unavailable when the plan cannot be bought on this server.
Body parameters
standard or team. 400 invalid_plan otherwise.Returns
{url, kind}. The link works once and for a short time.curl -X POST https://api.kaimei.ai/v1/billing/checkout \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"plan": "team"}'{
"object": "billing_redirect",
"url": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3…",
"kind": "checkout"
}#Open the billing portal
/v1/billing/portalOwner session onlyA link to Stripe's customer portal for the workspace: the card on file, the billing address and tax id, past invoices, and cancelling or renewing the plan. Owners only. 409 no_billing_account for a workspace that has never started a checkout.
Body parameters
cancel opens the portal on cancelling the subscription. Left out, it opens on its home page.Returns
{url, kind}, with kind portal.curl -X POST https://api.kaimei.ai/v1/billing/portal \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"flow": "cancel"}'{
"object": "billing_redirect",
"url": "https://billing.stripe.com/p/session/live_YWNjdF8x…",
"kind": "portal"
}#Check the subscription now
/v1/billing/refreshAdmin session onlyRead the subscription from Stripe and apply it, instead of waiting to be told. A customer can return from a Stripe page a moment before Stripe's own notice arrives, so the dashboard calls this when they land. Owners and admins.
Returns
curl -X POST https://api.kaimei.ai/v1/billing/refresh \
-H "Authorization: Bearer $SESSION_TOKEN"{
"object": "billing",
"enabled": true,
"plan": "team",
"status": "active",
"subscribed": true,
"custom": false,
"renews_at": "2026-12-19T09:30:11Z",
"cancels_at": null,
"payment_failed": false,
"has_billing_account": true,
"can_manage": true,
"plans": [
{
"object": "plan",
"id": "free",
"name": "Free",
"description": "Everything you need to upload a model, explain it and watch it in production.",
"price": {
"amount": 0,
"currency": "usd",
"interval": "month"
},
"limits": {
"models": 10,
"api_keys": 5,
"predictions_per_month": 5000,
"explanations_per_month": 500,
"analyses_per_month": 20
},
"rate_limit_factor": 1,
"members": false,
"purchasable": false
},
…,
{
"object": "plan",
"id": "team",
"name": "Team",
"description": "An organization for your whole team, with owner, admin, member and viewer roles and higher limits.",
"price": {
"amount": 2500,
"currency": "usd",
"interval": "month"
},
"limits": {
"models": 100,
"api_keys": 50,
"predictions_per_month": 200000,
"explanations_per_month": 20000,
"analyses_per_month": 500
},
"rate_limit_factor": 10,
"members": true,
"purchasable": true
},
…
]
}#List invoices
/v1/billing/invoicesAdmin session onlyThe workspace's bills, newest first. url is the invoice as a page and pdf as a file, both hosted by Stripe. Owners and admins.
Query parameters
1 to 100.
Returns
{object: "list", data, has_more}. Each invoice: id, number, status (open, paid, uncollectible or void), total in the smallest unit of currency, created_at, url, pdf.curl https://api.kaimei.ai/v1/billing/invoices \
-H "Authorization: Bearer $SESSION_TOKEN"{
"object": "list",
"data": [
{
"object": "invoice",
"id": "in_1QK2mTLkdIwHu7ix0a9B4c7D",
"number": "KAI-0042",
"status": "paid",
"total": 2500,
"currency": "usd",
"created_at": "2026-11-19T09:30:11Z",
"url": "https://invoice.stripe.com/i/acct_1…",
"pdf": "https://pay.stripe.com/invoice/acct_1…/pdf"
}
],
"has_more": false
}#Events from Stripe
/v1/billing/webhookNo authenticationStripe calls this when a subscription changes; you never do. The only credential is Stripe's signature over the body, checked against the endpoint's signing secret, and a request without a valid, recent one is 400 invalid_signature. An event is treated as a prompt to read the subscription from Stripe again, so one that arrives late, twice or out of order changes nothing it should not. On a self-hosted Kaimei, kaimei-api billing setup --apply creates the endpoint in your Stripe account and prints its signing secret, to set as KAIMEI_STRIPE_WEBHOOK_SECRET. It needs an https KAIMEI_PUBLIC_API_URL, or --webhook-url: see Self-hosting.
Returns
{received, outcome}, where outcome is synced or ignored.{
"received": true,
"outcome": "synced"
}