Billing & plans

Billing happens at the organization level — one plan, one invoice, one payment method covering every workspace the organization owns. Everything in this guide lives on the Billing tab of Organization Settings (with usage figures on the neighbouring Usage tab).

If you only remember one thing: the Billing tab is two independent halves. Your billing details (legal name, address, VAT numbers) are always editable — they decide the tax treatment of every future invoice, so you can and should fill them in early. Payment collection (plans, cards, invoices) only appears once collection has been switched on for your organization by the platform operator; until then, those sections simply aren’t shown.

---

Who can manage billing

Every billing endpoint requires the organization action org:billing:manage, held by the built-in owner and admin organization roles — not by ordinary organization members. Workspace roles are irrelevant here: a workspace admin who is only an org member cannot see or change billing. See authorization for how the organization and workspace permission axes differ.

Billing state changes that need attention — a failed payment, a suspension — are notified to the same audience: people holding org:billing:manage, never the whole organization.

---

Plans and the trial

New organizations start on a 3-month free trial with generous but finite usage allowances. The trial is granted automatically at creation — it is never listed as a selectable plan, so it can’t be re-granted.

Once payment collection is enabled, GET /organizations/{organizationId}/billing/plans lists the plans your organization may move to: each has a display name, a monthly base fee, an optional user ceiling, and the usage allowances included before metered charges apply. Prices are per-currency — each currency has its own price list, and amounts are never converted between currencies.

Changing plan

Pick a plan and confirm (Change plan on the Billing tab, or PUT /organizations/{organizationId}/billing/plan). The semantics are deliberately simple:

• The change applies from your next billing period. There is no mid-period proration in either direction — the current period’s bill is never re-priced by a plan change made during it, whether you’re moving up or down.
• Choosing a plan while on trial ends the trial and starts a normal, active subscription.
• The trial plan can never be selected.

How plan limits relate to the limits framework

A plan carries two different kinds of numbers, and it pays to keep them apart:

• Included allowances are billing facts: how much of each metered measure (storage, rows, AI tokens, …) is included before overage lines appear on an invoice. Exceeding an allowance costs money; it doesn’t stop anything.
• Limits are enforcement facts: hard ceilings on what the organization and its workspaces may do. A limit resolves in a fixed order — an explicit per-organization override, else the value the subscription plan carries, else the platform default — so upgrading to a plan with higher limits raises them automatically unless an override pins them.

Current usage and monthly history are on the Usage tab (GET /organizations/{organizationId}/usage — usage figures only, no pricing). The limits themselves, and the whole quota ladder, are covered in organization administration.

---

Billing details (the billing profile)

GET /organizations/{organizationId}/billing/profile / PUT /organizations/{organizationId}/billing/profile — the “bill to” party printed on every invoice:

• Legal name — a company name, or a person’s name for a sole trader.
• Customer type — business or individual. This is not the same question as “do you have a VAT number”: a sole trader below the registration threshold is a business with no VAT number.
• Address and country — the country matters more than it looks: for electronically supplied services the place of supply is the customer’s country, so this field decides the VAT treatment and rate on your invoices.
• Billing currency — GBP, EUR, or USD. Your invoices are denominated in it.
• Send invoices to — a list of accounts-payable recipients (up to 10), because AP is typically a shared mailbox plus a named person rather than the organization owner.
• Purchase order reference — optional, printed on every invoice; many AP systems reject an invoice without a matching PO.

Updates are partial: fields you omit keep their stored value, so a form that renders half the profile can’t blank the other half.

Note

The profile also carries a collection method (automatic card charge versus invoice-on-terms with net-N payment terms). These fields exist in the API but have no self-serve UI today — invoice-on-terms arrangements are set up with the platform operator.

Tax IDs (VAT numbers)

Tax identifiers are recorded per country: PUT /organizations/{organizationId}/billing/tax-ids adds or replaces your number for one country; DELETE /organizations/{organizationId}/billing/tax-ids/{countryCode} removes it. Numbers are accepted with or without the country prefix, spaces, and punctuation, and stored normalised.

Validation is asynchronous: the number is stored as unvalidated and a nightly job checks it with the issuing authority (VIES for EU numbers, HMRC for UK). The possible verdicts:

Status	Meaning
unvalidated	Not checked yet. VAT is charged until a check succeeds — the safe direction.
valid	Confirmed with the authority. EU business customers with a confirmed number are not charged VAT (reverse charge).
invalid	The authority does not recognise the number. Check for typos — VAT is charged until it’s confirmed.
unavailable	The national registry could not be reached. Not a rejection — the previously stored verdict still stands.

Where the authority discloses it, the registered name it holds for the number is shown — a mismatch against your legal name is worth a second look. Changing a stored number discards the previous verdict entirely: it evidenced a different registration.

---

Payment methods

Card capture uses a provider-hosted session — card details go straight from your browser to the payment provider and never touch Tessule:

1. Add a payment method starts a session (POST /organizations/{organizationId}/billing/payment-method-session) and sends your browser to the provider’s secure page.
2. You enter the card there and are returned to Tessule.
3. The card is recorded from the provider’s signed webhook, never from your browser’s return trip — so there can be a short “confirming your card…” wait after you return, while the app polls GET /organizations/{organizationId}/billing for the method to appear.

Stored methods are described only well enough to recognise — brand, last four digits, expiry. One method is the default, which is the card collection charges.

Removing a card

DELETE /organizations/{organizationId}/billing/payment-methods/{paymentMethodId} removes a stored method — with one guard: removing your last method is refused while anything still bills to it (an outstanding invoice, or a live subscription on a plan with a positive base fee). Add a replacement card, settle the balance, or cancel the subscription first; once nothing depends on it, the last card can always be removed.

Caution

In environments using the mock payment provider (a banner on the Billing tab says so), no real card is stored and no real money moves.

---

Invoices

Invoices are generated monthly, one per billing period, and listed newest first (GET /organizations/{organizationId}/billing/invoices, detail at GET /organizations/{organizationId}/billing/invoices/{invoiceId}).

An invoice’s lines itemise the bill: a plan fee line, plus a metered overage line per measure that exceeded its included allowance — each showing the used / included / billable quantity triple, which is what makes even a £0 invoice documentary rather than empty. Line amounts can be negative (discounts and credits). The detail view also lists every payment attempt, including the card issuer’s decline reason when one failed.

Invoice statuses: draft (period still being assembled), issued (collectable), paid, payment_failed (a retry is scheduled), uncollectible (retries exhausted — a person needs to act), and void. An issued invoice with a zero total settles as paid immediately, without touching the payment provider.

---

When a payment fails

The dunning path: bounded retries, an explicit past-due grace period, then suspension. Data is never deleted.

Collection follows a deliberately short, finite path:

1. Retry ladder. A recoverable (“soft”) decline is retried on a bounded schedule — by default on days 0, 3, 5, and 7 after the invoice becomes collectable, four attempts in total. Hard declines (card reported lost or stolen, fraud flags, “card not supported”…) stop immediately: retrying those is futile and harms everyone, so a different card is required instead.
2. Past due. When the ladder is exhausted — or there is no card on file at all — the invoice becomes uncollectible and the organization goes past due. You keep full access; banners and notifications (to org:billing:manage holders) are the only consequence, and the Billing tab shows the exact deadline.
3. Suspension. If the balance is still unsettled when the grace period expires (14 days by default), the organization is suspended: changes are blocked, but your data is intact and can still be read and exported. Nothing is deleted.
4. Restoration. Settling the outstanding balance restores the organization automatically.

Pay now

POST /organizations/{organizationId}/billing/invoices/{invoiceId}/pay (Pay now on an unpaid invoice) attempts collection immediately against the payment method on file and resets the retry ladder — it works even after the ladder is exhausted. Use it when you’ve just fixed the problem (added a working card, freed up funds): waiting for the next scheduled sweep is how an invoice stays unpaid. The response tells you plainly what happened: paid, retry_scheduled (failed recoverably), uncollectible (hard decline or ladder exhausted), no_payment_method (add a card first), or paid_zero (there was nothing to charge).

Tip

If a payment failed because of a broken card, the order that gets you out fastest is: add a new card (it becomes available immediately once confirmed), then Pay now on the outstanding invoice. If there was simply no card on file, adding one is enough — no attempts were burned, and collection starts cleanly.

---

FAQ

Q: I changed plan mid-month — what will this month’s invoice show?

The plan that was in force for the period being billed. Plan changes are never prorated and never re-price the period they’re made in; the new plan’s fee and allowances apply from the next period.

Q: Why can’t I see the plans / payment method / invoices sections at all?

Payment collection hasn’t been enabled for your organization (it’s an operator decision, not a setting you can reach). Your billing details and VAT numbers are still editable — fill them in so your first invoice is correct. If you can’t see the Billing tab at all, you’re not an organization owner or admin.

Q: We’re an EU business — why are we still being charged VAT?

Your VAT number’s status is probably still unvalidated or invalid. Numbers are checked nightly with the issuing authority, and VAT is charged until a check confirms the number. Check the status chip next to the number on the Billing tab.

Q: Does a suspended organization lose data?

No. Suspension blocks writes; reads and exports keep working, and everything is restored the moment the balance is settled.

Q: Where do I see what we’re being charged for usage?

Each invoice’s detail itemises every metered measure with used, included, and billable quantities. For live figures before the invoice exists, use the Usage tab — see organization administration.