Billing
How an organisation will pay for its plan and FurniOps AI credit. Billing is switched off today. What the billing API and Settings › Billing show, and how subscribing, changing plan, the card, invoices and credit work once selling starts.
Billing is switched off
FurniOps is not selling plans yet. Until it does, GET /v1/billing
answers enabled: false, every billing change answers 409 conflict, the
invoice list is empty, and Settings › Billing says billing is not enabled yet. Your plan is
the one FurniOps assigned to your organisation.
This page describes how billing works so you can build on it now; nothing here charges anyone while billing is off.
Who can see and change it
| Needs | Held by | |
|---|---|---|
| Read the plan, card and invoices | billing:read | Owners and admins, and an API key that holds it. |
| Subscribe, change plan, change the card, cancel or resume | billing:write | Owners only. No API key or OAuth app can hold it. |
What billing shows
{
"object": "billing_account",
"enabled": false,
"plan": "founding",
"subscription": null,
"card": null,
"plans": []
}| Field | Meaning |
|---|---|
enabled | Whether billing is switched on. |
plan | The organisation's current plan. |
subscription | The subscription, when there is one: Stripe's status, the plan, when the period ends, and whether it cancels then. |
card | The card renewals are charged to: brand, last four digits and expiry. |
plans | The plans on sale, each with its monthly fee and the usage priced past what it includes, in blocks. |
subscription.scheduled_change | A change held for the end of the term (a downgrade, or annual to monthly), with when it takes effect; null when none. |
details | Who invoices and receipts are made out to: the business name (the organisation's own unless set) and the billing email Stripe sends them to. |
credit_balance | Credit on the account from a plan change's proration or a refund, in currency's minor units. It pays the next invoices before the card is charged. |
overdue_invoice | While a renewal is past due: the unpaid invoice, with Stripe's page to pay it. A new card also pays it at once. |
How it will work
Payments go through Stripe, inside the dashboard's own form (Stripe's Payment Element): you never leave FurniOps for a checkout page. Card details go from your browser straight to Stripe; FurniOps never sees them. The API hands the browser only the secret it confirms a payment or a card setup with.
Your plan changes when Stripe confirms the payment to FurniOps, within seconds: never because a browser said so.
| Action | Dashboard | API | What happens |
|---|---|---|---|
| Subscribe | Choose a plan | POST /v1/billing/subscription | A subscription starts on the plan, renewing on the 1st of each month (UTC), with the first, partial month prorated. You confirm the first payment with your card. |
| Change plan | Change plan, Pay and change plan | the same call | The subscription moves to the plan with proration. A payment due now is confirmed first, and the plan changes only once it succeeds. |
| Change the card | Add a card, Update card | POST /v1/billing/card | You confirm a card setup; once Stripe confirms it, renewals are charged to the new card. |
| Cancel | Cancel subscription | POST …/subscription/cancel | The subscription ends with the current period. The plan stays until then, then returns to the default plan FurniOps assigns. |
| Resume | Resume subscription | POST …/subscription/resume | Undoes a cancellation before the period ends. |
| Keep the current plan | Cancel scheduled change | POST …/scheduled-change/cancel | Drops a change held for the end of the term; the plan renews as it is. |
| Edit who invoices are for | Edit details | PATCH /v1/billing/details | Sets the business name and billing email on future invoices and receipts. Leave the name blank to follow the organisation's name. |
Before you subscribe or change plan, POST /v1/billing/preview
prices it: timing says whether it happens now (and amount_due is charged today, after any
credit_applied) or is scheduled for effective_at (nothing is charged today). Send its
quoted_at back with the subscribe call to be charged exactly what was quoted. A card Stripe
declines answers 402 payment_declined, and nothing changes.
Invoices (GET /v1/billing/invoices) are listed newest
first, each with links to Stripe's hosted page and its PDF.
A renewal that fails leaves the subscription past_due while Stripe retries, and the dashboard
says the last renewal did not go through.
FurniOps AI credit
Credit keeps FurniOps AI answering once a day's included allowance is spent. It is US dollars at list price (1 credit is 1¢), bought once, never renewing, and it expires 12 months after payment; the credit that expires first is spent first. Settings › Billing › FurniOps AI credit shows it.
| Action | Needs | API |
|---|---|---|
| Read the balance, today's spend and what can be bought | billing:read | GET /v1/billing/credits |
| Read the ledger and the purchases with their receipts | billing:read | GET /v1/billing/credits/entries, GET /v1/billing/credits/purchases |
| Read the rate card: what each model costs in credit | Any member | GET /v1/billing/credits/rates |
| Price a purchase, with tax | billing:write, a person | POST /v1/billing/credits/purchases/preview |
| Buy credit | billing:write, a person | POST /v1/billing/credits/purchases |
| Change how credit is spent | billing:write, a person | PATCH /v1/billing/credits/settings |
A purchase is a one-off invoice with tax, paid in the dashboard's own card form. Credit is added
only once Stripe reports the invoice paid: poll
GET /v1/billing/credits/purchases/{purchase} until it
is succeeded or failed. The same Idempotency-Key answers the same purchase. No API key,
OAuth app or FurniOps AI itself can buy credit or change how it is spent.
Usage and limits
What each plan includes, and what happens at a quota, is in Usage and quotas and Plans and features.
Audit log
The organisation's one timeline of who did what, from sign-in policy to API keys and data operations. What is recorded, what an entry holds, filtering it in the dashboard and the API, and how long it is kept.
Sources
A source is one connection to a vendor's data. The kinds of source, what FurniOps can read today, creating one through the API, credentials, schedules, testing, and how FurniOps judges a source's health.