Billing

Anona holds the Stripe relationship, so you never touch Stripe keys directly. Paid-plan changes go through Stripe Checkout or the Customer Portal; free-plan changes happen in place.

Method and path	What it does	Role required
`GET /v1/billing`	Current plan, credit usage, and available plans.	Any member
`POST /v1/billing/upgrade`	Moves to a free plan, in place.	Owner or admin
`POST /v1/billing/checkout`	Starts Stripe Checkout for a paid plan.	Owner or admin
`POST /v1/billing/portal`	Opens the Stripe Customer Portal.	Owner or admin
`POST /v1/billing/cancel`	Cancels at the end of the billing period.	Owner

View billing status

GET /v1/billing returns the current plan, credit usage, and every plan you could switch to. credits_reset_at is when the credit allowance refreshes: on a paid plan, the end of the Stripe billing period, so it falls on the day of the month you subscribed; on Free, the signup anniversary. It is not the 1st of the calendar month. A date landing in a month too short for it (the 31st, in February) moves to the last day of that month.

current_month_ops and the line_items counts are still measured over the calendar month to date, which is a different window from the credit period whenever your billing date is not the 1st. credits_used is the figure that matches credits_reset_at.

{
  "plan_id": "starter",
  "plan_name": "Starter",
  "price_per_month_usd": 9.0,
  "credits_limit": 6000,
  "credits_used": 1240,
  "credits_remaining": 4760,
  "credits_reset_at": "2026-09-20T14:32:11Z",
  "rate_limit_per_min": 30,
  "has_subscription": true,
  "current_month_ops": 620,
  "memories_added": 400,
  "searches": 200,
  "insights": 20,
  "line_items": [
    { "op_type": "Memories Added", "count": 400, "unit_price": 2.0, "subtotal": 800.0 },
    { "op_type": "Searches", "count": 200, "unit_price": 1.0, "subtotal": 200.0 },
    { "op_type": "Insights", "count": 20, "unit_price": 5.0, "subtotal": 100.0 }
  ],
  "available_plans": [
    { "plan_id": "free", "name": "Free", "price_per_month_usd": 0.0, "credits": 500, "rate_limit_per_min": 10, "max_spaces": 1 },
    { "plan_id": "pro", "name": "Pro", "price_per_month_usd": 49.0, "credits": 40000, "rate_limit_per_min": 150, "max_spaces": 20 }
  ]
}

line_items is credit-cost accounting, not a Stripe invoice. The amount you are actually billed comes from Stripe.

Change plan

Free tiers

POST /v1/billing/upgrade

{ "plan_id": "free" }

Valid only for plans priced at zero. Any paid plan returns 400 payment_required and directs you to /v1/billing/checkout instead.

Paid plans

POST /v1/billing/checkout

{ "plan_id": "pro" }

{ "checkout_url": "https://checkout.stripe.com/c/pay/..." }

Redirect the user to checkout_url. Stripe’s webhook flips the organization onto the new plan and syncs its quota once payment completes, so polling /v1/billing right after the redirect may still show the old plan for a few seconds.

Manage an existing subscription

POST /v1/billing/portal requires an existing Stripe customer, meaning you have completed checkout at least once.

{ "portal_url": "https://billing.stripe.com/p/session/..." }

Redirect the user there to update a payment method, view invoices, switch between paid plans, or cancel. Plan switches are prorated by Stripe, which is why they belong in the portal rather than in a second checkout. An upgrade applies immediately, and the organization’s unused credits are added on top of the new plan’s allowance for the current period. A downgrade is scheduled for the end of the period already paid for, exactly like a cancellation: the organization keeps the larger plan and its limits until then, and GET /v1/billing keeps reporting the larger plan until the change lands.

Cancel

POST /v1/billing/cancel

{ "message": "Subscription will cancel at end of billing period." }

Cancellation takes effect at the end of the current billing period, the same date as credits_reset_at. The organization keeps its paid plan and credits until then.

Error responses

Status	Code	Cause
400	`payment_required`	`/upgrade` was called with a paid plan. Use `/checkout`.
400	`invalid_plan`	`/checkout` was called with a free or unknown `plan_id`.
400	`no_subscription`	`/portal` or `/cancel` was called with no Stripe subscription on file.
403	`insufficient_role`	The caller’s role does not permit the billing action.
409	`subscription_exists`	A subscription is already active. A second checkout would create a second subscription and bill twice, so plan changes go through `/portal`. Also returned by `/upgrade` when downgrading to Free while Stripe is still billing. Cancel in the portal instead.
409	`checkout_in_progress`	A checkout for a different plan is already open for this organization. Finish or abandon it first; retrying the same plan is allowed and returns the original session.
503	`billing_not_configured`	Stripe is not configured on this deployment.
503	`price_not_configured`	No Stripe price is configured for that plan.

See the full error reference.

API Essentials

Memory (data plane)

LLM Proxy (drop-in)

Account (control plane)

View billing status

Change plan

Free tiers

Paid plans

Manage an existing subscription

Cancel

Error responses

​View billing status

​Change plan

​Free tiers

​Paid plans

​Manage an existing subscription

​Cancel

​Error responses

View billing status

Change plan

Free tiers

Paid plans

Manage an existing subscription

Cancel

Error responses