Billing

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.

PlanWho it is forBought here
freeEvaluation. Where every workspace starts, and where it returns when a subscription ends.No payment
standardOne person who needs higher limits.Yes
teamAn organization. Higher limits again, and the plan an organization needs before it can have more than one member.Yes
enterprisePrivate 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

enabledboolean

Whether plans can be bought through this server. false on a self-hosted Kaimei with no Stripe key.

planstring

The plan the workspace has now: free, standard, team or enterprise.

statusstring
none when there is no subscription. Otherwise Stripe's word for it: active, trialing, past_due, canceled, unpaid, incomplete, incomplete_expired or paused.
subscribedboolean

Whether a subscription made here is paying for the plan.

customboolean

The plan was set by Kaimei under a contract. It is not bought or changed through these endpoints.

renews_attimestamp | null

When the next payment is taken.

cancels_attimestamp | null

Set once the subscription has been cancelled: when it stops and the workspace goes back to free.

payment_failedboolean

The last payment did not go through, and Stripe is retrying it.

has_billing_accountboolean

Whether there is anything for the portal to show.

can_manageboolean

Whether the caller may change the plan: an owner of the workspace.

plansarray

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.

Example
{
  "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

GET/v1/billingSession token only

The 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

A Billing object.
curl https://api.kaimei.ai/v1/billing \
  -H "Authorization: Bearer $SESSION_TOKEN"
200 OKResponse
{
  "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

POST/v1/billing/checkoutOwner session only

A 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

planstringrequired
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"}'
200 OKResponse
{
  "object": "billing_redirect",
  "url": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3…",
  "kind": "checkout"
}

#Open the billing portal

POST/v1/billing/portalOwner session only

A 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

flowstringoptional
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"}'
200 OKResponse
{
  "object": "billing_redirect",
  "url": "https://billing.stripe.com/p/session/live_YWNjdF8x…",
  "kind": "portal"
}

#Check the subscription now

POST/v1/billing/refreshAdmin session only

Read 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

The Billing object, as it is now.
curl -X POST https://api.kaimei.ai/v1/billing/refresh \
  -H "Authorization: Bearer $SESSION_TOKEN"
200 OKResponse
{
  "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

GET/v1/billing/invoicesAdmin session only

The 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

limitintegeroptionaldefault 12

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"
200 OKResponse
{
  "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

POST/v1/billing/webhookNo authentication

Stripe 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.
200 OKResponse
{
  "received": true,
  "outcome": "synced"
}