Billing

Billing is where money lives. The heading reads Billing and the subtitle "Your estimated charges for the current billing period." A period chip beside it shows Current period · "{start} – {end}" · renews {date}.

Owners and admins only

Billing is restricted to organization owners and admins. Everyone else sees a single card: "Billing is visible to organization owners and admins."

Billing stays reachable if your organization is suspended

A suspended organization keeps access to this page on purpose — you can still review your statements and pay an outstanding invoice, which is usually exactly what is needed to lift the suspension. A banner explains the situation. Everything outside billing, including inference, is refused for the duration.

The restricted session is created at your next sign-in. If you were signed in when the suspension took effect, sign in again to get it.

What you will actually see

Under the header and period chip the page is one spine of four regions, always in that order. The regions are always there; only what is inside them changes.

Region	What it holds
What you owe	Current period usage, your plan and its renewal, and a commitment summary where you have one
What you have	Your wallet and Redeem a coupon, and the spend limits that refuse a request before it is charged
What you are using	Usage value: this period's usage at list price, before your plan or contract is applied
What you have been charged	Statements & transactions, your cards on file, and every payment attempt

Most organizations are on Pay as you go, a postpaid plan with a zero monthly fee, no included tokens, no commitment and no credit ceiling. The plan card, the included-allowance breakdown, the wallet balance, Add funds and the cards on file are all conditional, and such an account will not see them. They are described further down, under the conditions that make them appear.

A region never goes quiet

Where a card cannot be shown, the region carries a sentence saying why instead of an empty space or a misleading $0.00. Prepaid credit that is not enabled for your organization, a balance or a plan that could not be read, statements that are not enabled, and a plan that charges no fee and grants no allowance each have their own sentence, and each says where the figure you were looking for actually is.

Current period usage

What this card shows depends on how your organization pays.

On a prepaid account it is a single figure for what your organization has accrued so far, captioned:

Usage accrued so far this period, invoiced at the end of the billing period.

Your wallet is drawn as the period settles, so the figure is the spend the wallet has not been debited for yet.

On a postpaid account nothing is drawn from a wallet, so a single accrued figure was never the whole story. The card carries three:

Figure	What it counts
Unbilled usage	Service already delivered that no document bills yet
Issued, unpaid	Issued statements, net of payments, discounts, write-offs and credit notes
Total outstanding	The two added together — what your organization owes right now

Three things worth knowing about them:

• Unbilled usage covers every uninvoiced period, not only the current one. A period that has closed but has not been invoiced yet is counted here rather than vanishing until its document arrives.
• Your plan's included allowance and a commitment's negotiated rates are already netted out. This is what the closing document will bill, not a list-price valuation of your traffic. For that, see Usage value.
• A figure that cannot be worked out reads —, never $0.00. The card says so and points you at Statements & transactions. It will not tell you that you owe nothing because a number was unavailable.

The card is shown to a postpaid organization on any plan shape, including one with a plan fee or an included allowance.

This is not the wallet's "unsettled usage"

On a prepaid account, unsettled usage is spend the wallet has not been debited for, and settlement collects it. On a postpaid account, settlement records the same usage and collects nothing — the money becomes a statement — so that figure empties on every settlement run while the debt keeps growing. On a postpaid account, read the three figures above instead.

Redeem a coupon

A Coupon code field and a Redeem button, footnoted:

Coupon credit is spent before top-up credit, and credit already in your wallet never expires mid-period.

Codes are matched without regard to capitalisation, and spaces at either end are ignored: welcome50, WELCOME50 and Welcome50 all redeem the same coupon. Type the code the way you were given it — a capitalisation slip is not a wrong code, and a code pasted with a trailing space still works.

A code that does not exist and a code that exists but was issued to a different organization are refused identically, on purpose: the refusal never confirms whether a code exists. If a code you were given is refused, check it with whoever issued it rather than trying variations.

Redeeming a coupon is what brings the wallet into view. See below.

Your wallet

The wallet section appears only once your wallet holds a positive balance. In practice that means after you redeem a coupon or receive a top-up. Until then the balance, the coupon / top-up / promotional breakdown, the credit-lots table and the Add funds button are all absent from the page.

When it is shown, the credit-lots table lists your credit in the exact order it will be spent, with each lot's remaining amount and expiry. The headline balance counts only drawable credit: an expired lot is worth zero and never inflates the total.

How the balance breaks down

Line	What it counts
Coupon credit	Credit from redeemed coupon codes
Top-up credit	Money you paid by card, and nothing else
Account credit	Credit the platform granted you — goodwill adjustments, corrections for over-collection
Promotional credit	Credit from promotional grants

The four add up to the total balance.

Account credit is not money you paid

Top-up credit counts card payments only. Credit the platform issued to make you whole for something is reported separately as Account credit so the tile cannot read higher than what you were actually charged. Account credit is fully drawable and pays invoices; it just cannot be refunded to a card, because no card was charged for it.

Held balance

Part of your balance can be held: still yours, still counted in the total, but not spendable while the hold lasts. Available balance is your total minus everything held, and that is the figure requests are admitted against.

Two things place a hold, and the wallet names which.

A request that is running

On a prepaid account, every request holds its estimated cost while it runs and releases the hold when it ends. These holds are short-lived and you will usually never see one. See How a request is admitted against your balance.

An open payment dispute

If a card payment is disputed with your bank, the disputed amount alone is held while the case is open:

• Total balance does not move. The money is still yours.
• Available balance falls by the held amount.
• The rest of your wallet keeps working normally. This is not an account suspension, not a whole-wallet freeze, and it does not stop you adding funds.
• The hold is lifted when the case closes. If you win, the money becomes spendable again; if you lose, the hold is consumed by the clawback rather than being released and re-taken.

While a dispute hold is in place, a refund of the disputed payment is also limited by it — the disputed money may not leave in either direction until the case resolves.

Unlike a request's hold, a dispute hold has no expiry: it lasts exactly as long as the case does.

How a request is admitted against your balance

On a prepaid account the platform holds the estimated cost of a request against your wallet before the request runs, and releases the hold the moment it ends. A hold is a reservation, never a charge — what you pay is still the usage you actually got.

• The estimate is the worst case. For a token request that is your input plus the largest output the request could produce — its max_tokens, or a platform default when you do not set one — priced at the rates that apply to your account. Streaming is not treated differently.
• It is all or nothing. If your available balance cannot cover the whole estimate, nothing is held and the request is refused with 402 before any work is done. Nothing is charged, and the request succeeds on a straight retry once you have added funds.
• Concurrent requests each hold separately. Firing many requests at once does not let them all through against one balance: each takes its own hold, and the ones the balance cannot cover are refused while the rest run.
• Audio holds its exact price, not an estimate. A speech or transcription request is priced before it is sent, so an unaffordable one is refused up front rather than after the audio has been produced.
• Realtime sessions are covered by the same reservation, taken again as the session meters. A session that runs out of balance part-way through is closed cleanly rather than surfacing as a fault.

Two cases are deliberately never refused this way:

• Postpaid accounts. Nothing is drawn from a wallet, so admission is governed by your credit limit instead.
• A plan customer still inside their included allowance. Usage your plan covers is not wallet money and is never refused for a wallet reason. See Plans.

The refusal is an ordinary 402 carrying insufficient_credits, with the same body and the same limit_type a depleted wallet has always returned. For the code table and how to branch on it, see Error Handling.

Service delivered beyond your balance is still owed

A hold bounds a request before it runs, but it is an estimate, so a small overshoot remains possible. Anything delivered above your balance is recorded as owed, not written off — it is collected the next time your wallet is funded, and it shows up in your statements like any other charge.

Low-balance notifications

On a prepaid account you are emailed when your credit is running low, and again if it runs out.

The low-balance threshold is relative to your own consumption — roughly a week of your recent daily average — rather than a fixed platform figure. A high-volume account is warned at a correspondingly larger number, and a brand-new account with no usage yet is not warned at all.

Adding funds

Add funds opens a dialog on the Billing page itself, in front of the balance it is about to change. There is no separate page to navigate to.

1. Choose an amount. Four preset buttons cover the common cases; the free-text field takes anything else. Beneath it, a line states the range the server actually accepts, for example "Between $1.00 and $50,000.00." Presets outside that range are not offered.
2. Billing details, if your organization has not supplied them yet. See Billing details below.
3. Pay. You are redirected to the payment provider's own hosted page, where you enter your card details.

Two things the dialog tells you as you type:

• The effective balance after this payment, updated live. If the amount you picked would still leave you at or below zero, the figure turns red and says so — so you find out before paying, not after.
• The real number of steps in the flow. An organization whose billing details are already on file sees two steps, never a promised form that does not arrive.

The amount you choose is the credit you get

The presets and the amount you type are net — that is what reaches your wallet, and it is the number you are choosing. Under the summary the dialog says where tax is determined:

Tax calculated at checkout The amount you choose is the credit that reaches your wallet. Our payment provider works out any tax that applies from your billing address and adds it to the card charge.

Behind Why your card can be charged more than this sits the longer explanation: we never work tax out ourselves; the provider determines it at checkout from your billing address, adds it to what it charges your card, and states it on the invoice it issues you for that payment. So the card charge can be higher than the amount above, while your wallet is always credited the amount you chose — your balance is never the figure with tax in it.

Where we do not hold a complete billing address, the dialog says so instead, because the provider needs one before it can work any tax out.

No estimate is shown before you pay

The dialog states where tax is worked out, never a figure. Nothing on this side computes a rate, so an estimate here would be invented rather than quoted. The real figure appears on the provider's hosted page before you confirm, and afterwards on the transaction row — see What a card payment actually cost.

Card details are never entered on our pages

Payment is taken on the provider's own hosted page after a full browser redirect. The portal loads no third-party payment script and has no card field of its own.

Adding funds is for prepaid organizations

If your organization is postpaid, usage is invoiced at the end of the period and there is nothing for a wallet balance to do. The Add funds control is not offered. See Billing modes for which mode you are on — the wallet section names it.

If the platform does not take cards

Some deployments do not offer card payment at all, because no payment provider is configured on them. On such a platform the portal withdraws the offer rather than letting it fail: Add funds and its dialog are not shown, an invoice carries no Pay by card action, and the wallet row carries a sentence where the button would be:

Card payment is not available on this platform. Contact us to arrange payment for your account.

Everything else on Billing is untouched. Your balance, the credit-lots table, your statements and every invoice figure read exactly as they always did, and Redeem a coupon keeps working: a coupon needs no payment provider, so on a platform like this it is how credit reaches your wallet. To settle what you owe, contact us and we will arrange it.

If a payment does not complete

The return page never treats your arrival back on it as proof of payment. It polls until the server has actually committed the result, showing "we are confirming your payment" in the meantime.

• If the payment succeeded, the wallet reflects it and a Top-up row appears in Transactions.
• If it failed or was declined, nothing was charged and the page says so. Try again retries the payment that failed — the same invoice or the same plan order — rather than dropping you on a blank top-up form.
• If you cancelled it on the provider's page (its own back or cancel control), you land on a neutral "You cancelled this payment" panel almost immediately, naming the amount that was not charged and offering Try again. See Cancelling a payment below.
• If you abandoned it (closed the tab at the provider), the attempt is recorded as abandoned as soon as the provider reports that page closed, rather than only after it times out.

Whether money moved is always read from the server, never from the address you came back on. Returning to a bookmarked or re-used return link for a payment that did go through still shows you the receipt for it, not a cancellation.

Reloading the page after a successful payment never tells you the payment failed.

Cancelling a payment

Coming back through the provider's own cancel control does more than close our record of the attempt: the portal asks the provider to expire the payment page itself. Once that succeeds the page can no longer take a card — not from your browser history, not from another device, and not from a tab you left open behind you.

The page only promises what it could confirm:

What you read	What it means
"nothing has been charged and nothing will be — we closed that payment page, and it can no longer take a card"	The provider confirmed the page is closed. There is nothing left to do.
"nothing has been charged. We could not confirm … so do not go back to it or reuse its link — it may still accept a card for a short while"	We could not reach the provider. Start the payment again from Billing instead of returning to the old page.
"Payment confirmed — We received ${amount}"	That page had in fact already been paid, in another tab or on another device. You get the receipt, and no claim that nothing was charged.

Every one of those ends on a panel with Try again and Go to billing; cancelling never leaves you without a way forward.

Cancelling closes a payment page. It never reverses money already taken — that is a refund.

Starting a new payment closes the previous one

Your organization has at most one payable page per thing being paid for. Starting a new top-up supersedes an earlier unfinished top-up, and starting a payment for an invoice supersedes an earlier attempt at that invoice. Topping up your wallet and paying an invoice are different things and never displace one another.

The page that loses is always the older one, so an old tab left open will show the provider's own "this session has expired" message. Open the current payment from Billing rather than reusing it.

If the amount is refused

Amounts outside the accepted range are refused with the range named:

That amount is outside the range we can accept. Enter between $1.00 and $50,000.00.

The exact bounds are configured per deployment, which is why the dialog reads them from the server rather than printing a fixed pair of numbers.

Billing details

Before your organization's first card payment, we need to know who the money is billed to. The form asks for:

Field	Required
Legal name	Yes
Country	Yes
Address	Yes
City	Yes
Postal code	Yes
State / Province code	Only for US, CA, AU and IN
Billing email	Yes
Tax ID	No
Address line 2	No

Tax ID is genuinely optional — individuals and customers outside jurisdictions that issue one can leave it blank and the profile still counts as complete.

City and postal code are required in every country, and a state or province is required in four. An address the payment provider cannot source a tax rate to is an address that fails at checkout rather than in the form, so the form asks for it up front. The State / Province code field is shown only for the countries whose tax is sourced to a subdivision — the United States, Canada, Australia and India — and takes the bare subdivision code, NY rather than US-NY. A country prefix is rejected rather than quietly stripped.

Adding this field does not make an existing profile incomplete

A billing profile that counted as complete before this field existed still counts as complete. Nobody becomes unable to pay because a new field appeared.

The form appears inside the Add funds flow as a step, not as an error after the fact, and the payment resumes with your chosen amount still in place once it is saved. Owners and admins can also edit it at any time from the Organization page.

Payments

The Billing page lists your organization's payment attempts, so an in-flight, declined, failed or abandoned payment is visible rather than silently missing.

Each row shows what the payment was for, its amount, when it was attempted, and its state:

State	Meaning
In progress	Started, not yet resolved
Succeeded	Money taken and credited
Failed / Declined	The card was refused. Nothing was charged.
Abandoned	The provider page was left without completing

Failed and abandoned attempts are shown neutrally rather than in an alarm colour: an attempt that did not complete took no money, and the row says so.

Cards on file

A Payment methods card lists the cards you have authorised us to keep: "Cards you have authorised us to keep. The card marked as default is the one we charge when a new billing period opens."

Each row names the card as "{brand} ending {last4}", with its expiry and the date it was added. One card carries a Default chip; the others offer Make default. Every row offers Remove.

With no card saved, the card says where one comes from rather than leaving you looking for a button that is not there: "No card on file. You can save one the next time you pay by card — there is a box to authorise it on the payment page."

Authorising a card at checkout

Cards reach this list one way: you tick the box on the payment page. It is headed "Save this card for future charges", it is off by default, and nothing is stored unless you tick it. Beside it, four statements you should read before you do:

What is stored	The card's brand, its last four digits and its expiry date, together with a token held by our payment provider. The card number never reaches us.
When it is charged	Automatically when each new billing period opens, and for any other charge that falls due while the card is on file.
How much	The amount on the invoice we raise for that period — your plan fee plus any usage beyond what the plan includes. We never charge a figure that is not on an invoice you can open.
How to stop it	Remove the card from Billing at any time. Nothing is charged to it after that, and removing it never affects a payment already made.

There is a second tick box, and it is not ours

Our payment provider asks you to agree on its own hosted page as well. That box is separate from this one and is required before the provider will take the payment — the page will not proceed until it is ticked, and it does not always say why. The checkout page warns you about it in advance for exactly this reason.

Leaving the box unticked is allowed, and paying for a plan change without it raises one extra confirmation rather than letting it pass silently: "Continue without saving your card?" — "Without a saved card we cannot renew this plan. It will end at the close of this billing period." The payment goes through either way and you keep the period you paid for; Go back returns you to the box, Continue without saving proceeds.

Making a card the default, and removing one

Make default switches which card the renewal charge uses. If it does not work, nothing is changed and the card says so.

Remove asks first: "We will stop using {card} and delete it from your account. Payments already made with it are not affected, and you can save a card again the next time you pay." Removing your last card while a plan is active adds a warning to that dialog and still lets you through:

This is your only card. Remove it and there will be nothing to charge when your next billing period opens, so your plan will end at the close of the current period. You can pay by card at any time before then.

The card is yours; the portal states the consequence rather than refusing.

A card on file is not the same as permission to charge it

A card that is stored but that nothing authorised us to charge on its own is labelled Not authorised for automatic charges and will not be used to renew your plan. Authorise it the next time you pay by card. For the same reason, removing a card detaches it — it is not a way to withdraw an authorisation you gave, and there is no control for that today. Contact us if that is what you need.

Refunds

A refund appears in the Transactions feed as its own kind of row — distinct from a top-up, with the reason and a reference to the payment it reverses. It is not painted the same green as money arriving.

Two limits apply to what can be refunded:

• A refund cannot exceed what was actually captured on that payment.
• A refund cannot exceed the unspent portion of your card money. Credit you have already spent on usage, and coupon or granted credit, are not refundable — there is no card payment behind them to return.

The advertised refundable amount is always a figure a refund will actually accept. A sub-cent remainder can be left behind in the wallet as spendable credit rather than being refunded.

Requesting a refund

There is no in-product refund request form. Contact your account manager or platform administrator.

Spend limits

The Spend limits section is hinted:

Limits refuse requests once reached; they never change your prices.

That is the whole idea. A limit stops traffic; it never alters what you are charged for the traffic that did go through.

Organization spending cap

This card renders for every organization, and it is the ceiling most customers will actually meet.

With no cap set it reads No cap set, with the body "Nothing stops your organization's usage at a set amount right now." and a Set a cap button.

With a cap set it shows the amount followed by / billing period, a you set this chip, and:

Applies to every member for one billing period. Requests are refused above the cap; your prices and invoices are unaffected.

Two buttons (Change cap and Remove cap) sit beneath, along with a meter reading "{spent} of {cap} used" and "{amount} left before requests stop".

Setting a cap

The field is labelled Cap per billing period (USD).

Rule	Detail
Minimum	Must be greater than 0. Zero is rejected; it is not a way to switch the cap off.
Precision	At most two decimals.
Maximum	None.
Takes effect	"A new cap applies from your next API request; there is no waiting period."

To switch the cap off, use Remove cap rather than setting it to zero. Removing is an inline confirmation:

Remove the cap? Your organization's usage will no longer be stopped at any amount.

When the cap is reached

The card flips to API requests are being refused. Requests from every member of the organization, not only the person whose traffic crossed the line, are refused with HTTP 402 and the error code payg_spend_cap_exceeded. Raising the cap or removing it restores service immediately.

The cap is measured at list price

The cap counts all usage recorded in the period at list price, including usage already covered by a plan or a commitment, and including audio spend. The figure it measures can therefore be considerably higher than the amount you are actually invoiced. Set the cap as a traffic ceiling, not as a budget target.

The request that reaches the cap still completes and is still billed; the next one is refused. Usage can therefore finish marginally above the number you set.

If your organization has no open billing period, the cap is not applied.

Your daily limit

Beside the organization cap sits Your daily limit, your own personal cap, with an Adjust button that takes you to Profile. It applies to your requests only. See Cost Limits.

Statements & transactions

Hinted:

A record of usage and amounts · the invoice for a card payment comes from the payment provider

Two tabs: Statements (the default) and Transactions.

Documents are born issued

There is no draft-then-finalise review step. A closing document is created issued; drafts are internal and are never listed. A document is corrected by recording a transaction against it or by issuing a credit note, never by editing it after the fact.

The Transactions tab is not tied to period close. Coupon redemptions, top-ups, refunds and daily usage summaries post ledger rows as they happen, so it fills up well before your first statement arrives.

A zero-total document is not emailed

A month spent entirely inside a plan's included allowance closes with a document whose total is 0.00. It is still issued and it is still listed here — you are simply not emailed about it, so statement mail stays worth opening.

The Statements tab

Column	Contents
Document	Document reference
Type	Period statement · Commitment charge · Subscription fee · Credit note · Manual statement
Date	Issue date
Amount	Document total
Status	Draft · Issued · Partially settled · Paid · Void

Paid and Partially settled are derived from what remains outstanding; they are never set by hand. Draft documents are internal and are not listed. Voided documents remain visible; a document is never quietly removed from your history.

The Transactions tab

Column	Contents
Transaction	Type
Date	When it posted
Description	Free-text detail
Amount	Signed value

Type	What it is
Statement issued	A document was raised. It creates debt, so it is a charge.
Statement settlement	Wallet credit was drawn to settle a document
Payment	A payment recorded against a document
Payment reversed	A payment previously received was undone. It restores debt, so it is shown as a charge, not as a credit.
Refund	Money returned to your card
Credit note	A corrective document
Statement adjusted	An operator correction to a document
Statement voided	A document was cancelled
Discount applied	A discount was granted against a document. This is a credit to you.
Coupon redeemed	A coupon code was redeemed
Top-up	Wallet credit purchased by card
Usage summary	One day's usage, summarised
Credit expired	A credit lot reached its expiry date unspent

Rows are classified by type, not by the sign of the amount. Credits render green with a leading +, debits red with a leading -, and a refund gets its own treatment rather than looking like money arriving.

What a card payment actually cost

Where you pay by card, the payment provider works tax out at checkout and issues you its own invoice for that payment. Both facts are reported back here.

A Top-up row keeps the amount that reached your wallet as its headline figure — that is the credit you bought and the money you can spend. Under it, a second line states what your card was actually charged, the tax inside it, and a link to the provider's invoice:

+$100.00 Paid $120.00 (incl. $20.00 tax) · Invoice ↗

The link opens the provider's invoice in a new tab.

Three rules decide what that line says, and no surface departs from them:

• Your wallet is always credited the net amount you chose. Tax is never spendable balance. A $100.00 top-up credits $100.00 whatever the card was charged.
• No tax means the clause is dropped, not shown as zero. A payment with no tax on it reads Paid $100.00 with no parenthesis.
• A figure we were not told is not invented. Where the provider stated no total, the secondary line is not rendered at all. The portal never computes gross − net and calls it tax, and never adds a tax it knows to a net and calls the result what you paid.

A statement paid by card carries the same link as Provider invoice in its detail footer rather than on the list row.

One link belongs to one payment, not to one document

The link identifies the payment, not the statement. A statement settled from your wallet has no provider invoice and never will; one closed by two card payments has two. That is why the link lives with the payment that raised it.

Usage summary rows

On a prepaid account, your spending appears in the feed as one row per day, not one row per request. Each row covers a single fully-elapsed UTC day and is written the following day, so today's usage is not in the feed yet — check Current period usage for the live figure.

Statement detail

Opening a statement shows its lines as Item | Qty | Unit price | Amount. Service periods are shown in UTC, with the end made inclusive so a period reads as the days it actually covers rather than stopping an instant short.

Each line names a Priced at source, one of:

• the rate in effect at the time of use
• your account's negotiated rate
• your plan's rate
• the standard rate

Token lines are priced per 1M tokens.

Audio lines carry a unit price too. The rate printed is per unit of that line's own quantity, so Qty × Unit price = Amount holds in the columns you are reading. Where the platform quotes a rate in a different denominator — text to speech is quoted per million characters — the description spells the quoted rate out, for example @ 15/1M characters, so the two can never be mistaken for each other.

If more than one rate genuinely applied to the same unit during a period — a negotiated rate that took effect mid-period, for example — that unit is shown as one line per rate rather than blended into an average that no price list reproduces. The lines add up to what a single line would have billed.

Totals below the lines cover Subtotal, Paid, Total, Applied to this statement, and then either Remaining or, when nothing is outstanding, Settled.

Where the statement was paid by card, the footer also carries a Provider invoice link to the invoice the payment provider issued for that payment. See What a card payment actually cost.

Applied to this statement lists three kinds of entry: Discount, Payment and Payment reversed.

Why "Payment reversed" is a positive number

A reversal undoes money previously received, so it raises what is owed. It is therefore shown as a positive, neutrally coloured amount rather than as a credit. Reading it as a refund to you would be backwards.

Once a document leaves draft, its money fields are fixed. A document that has taken money is corrected by recording a transaction against it, never by editing the document. That is why a reversal appears as its own line rather than as a changed total.

A payment can never exceed what remains on a document. Any surplus is credited to your wallet instead of overpaying the statement.

Who the document is billed to, and tax

Every document records the identity it is billed to — legal name, tax ID, country, address and invoice email — captured from your Billing details as they stood at the moment the document was issued.

• Correcting your billing details later applies to documents issued from then on. It never rewrites one already issued.
• A credit note copies its identity from the document it corrects.
• A document is issued and can be paid whether or not your billing details are complete; the document records which was the case rather than blocking you.
• Documents issued before these fields existed carry no identity. They were deliberately not filled in retrospectively, because a snapshot taken today would not be what was true then.

Documents also carry tax fields. On this platform they are written as a tax amount of zero with no tax rate determined. That is the literal position — nothing on the platform determines a rate per jurisdiction, per customer or per line — and it is deliberately not the same statement as "your rate is 0%". Tax is recorded at document level only; there are no per-line tax figures.

This is not in conflict with the tax you may see on a card payment. Any tax on a card charge is worked out and charged by the payment provider, and stated on the invoice it issues you — see What a card payment actually cost. The statement you are reading here records usage and the amounts it comes to; it is not the document that carries that tax.

The identity and tax figures are frozen along with the document's money fields once it is issued, and cannot be edited afterwards.

Paying a statement by card

An issued document with an amount remaining carries a Pay by card action. It runs the same hosted-checkout flow as Adding funds — billing details first if they are not on file, then a redirect to the provider's page — with the amount fixed at what the document owes.

• Draft, voided and credit-note documents are not payable and are not offered the action.
• On a platform that does not take cards the action is not offered on any document. See If the platform does not take cards.
• If the payment is declined, Try again returns you to that statement's payment, not to a blank wallet top-up. Paying a statement and topping up the wallet are different things and are never confused with one another.
• If a wallet settlement lands between starting checkout and the card being charged, the collectible part is recorded against the document and the remainder is credited to your wallet. You are never charged twice and nothing is lost.

Statement totals are rounded up to the whole cent, once, at document level. This is deliberate: audio is priced in fractions of a cent, and rounding half-up was closing low-volume periods at zero.

Every statement carries the notice:

This statement records the usage in this period and the amounts it comes to. It is a record we issue, not a tax invoice: where you pay by card, the invoice for that payment is issued by the payment provider.

Usage value

Hinted:

The list-price value of your usage this period, for reference. This is not your bill; usage within your plan's quota is already covered by the plan fee above.

The section carries a list price badge and shows Total usage value, Daily average and Peak day, a daily bar chart, and a Usage value by model band.

This is a reference view, not a charge. It is the figure to reach for when you want to know what your traffic is worth at standard rates, for example when judging whether a plan is saving you money.

If your plan charges a fee or grants an allowance

The plan surface renders when either is true of your plan: it charges a monthly fee, or it grants you an included allowance. Either one on its own is enough. A plan with a zero fee that still grants a real allowance — the shape used for pilots, trials and negotiated arrangements — gets exactly the same surface as a paid plan, minus the fee row. What the page asks is what your plan grants, not what it charges.

A plan that charges nothing and grants nothing is genuinely pay-as-you-go. It gets a lean current-period total instead, captioned "Billed at the end of this billing period." — the page does not claim a monthly calendar cycle it cannot know, because a billing cycle re-anchored by a change of billing mode is not a calendar month. On a postpaid account that total is not repeated here at all; Current period usage already carries it.

A plan card sits above Current period usage, breaking the period down into:

Line	Meaning
Plan fee	The plan's recurring fee for a complete plan period. Shown only when there is one — a plan that charges no fee gets no $0.00 fee row and no fee segment in the composition bar, because a zero row would claim a layer the bill does not have.
Quota overage	Usage beyond the included allowance, at the plan's overage rate
Out-of-plan models	Usage of models the plan does not include, at standard list rates
Estimated total this period	The running sum of the above

The card's summary line follows the same rule. A plan with a fee reads "This period is billed as a plan fee plus additional usage."; a zero-fee plan reads "This plan charges no fee. This period is billed as usage beyond what the plan includes."

The plan's renewal countdown names the next charge and what will pay for it: "Next charge {amount}, charged to {card}." Where there is nothing to charge it says so and gives you the date it matters by — "No card on file — your plan will end on {date}.", or, for a card that is on file but not authorised for automatic charges, "The card on file is not authorised for automatic charges, so your plan will end on {date}." See Cards on file.

Included allowances are shown per model, with meters against what has been consumed. See Plans for how allowances and overage pricing are defined — the allowance meters follow whether your plan grants quota, not whether it charges a fee.

A plan that includes no allowance at all is labelled Pay-as-you-go rates rather than being given a quota label it has no allowance to have. The note beside it says all usage is billed at your plan's rates, and never claims a monthly token allowance you do not hold.

Where the card declines to state a figure

Two states are reported plainly instead of being papered over:

• Usage has passed an allowance but no overage charge landed on this period's bill. The card says exactly that and points at the allowance section, rather than telling you your usage is within your quota directly beneath a band saying it is not.
• The consumption and overage figures reported for the period do not line up. No overage total is shown, and the card points you at the invoice for the period, which is the figure that counts. Nothing is reconciled or estimated on your behalf.

If a plan fee cannot be collected

A plan fee is charged to the card saved on your organization. When that does not work, what happens next depends on why:

Situation	What the platform does
No card on file	Nothing is charged and nothing is declined — there is no card to charge. You are emailed asking you to add a payment method.
Your bank declined the charge, with a retry still to come	You are emailed with the reason in plain words and the date of the next attempt.
Your bank declined it and no retry is left, or refused the card outright	The same email, carrying no retry date, because there is no further automatic attempt. A card the issuer refuses outright stops the schedule immediately rather than running it out — the next attempt would be refused identically.
Your bank asks you to authenticate the payment	A different email, carrying a link back to a live checkout, and a banner on this page. No automatic retry can complete an authentication you have to be present for.
The charge never reached your bank	Nothing is emailed. The schedule simply tries again.

The banner reads "Your bank needs you to approve this payment", names what is outstanding, and carries Approve the payment, which opens a fresh checkout for the invoice in question. It is the only route through: a charge we make on your behalf while you are not present will be declined the same way every time, however often it is retried.

Once collection has been given up on, your plan moves to pay-as-you-go at the end of the current billing period. Never mid-period: you paid for the period you are in, and you keep it in full. The move is scheduled exactly like a cancellation you requested yourself, so it appears on Recent plan changes and you can withdraw it — by settling the fee — at any time before the effective date. See Plans.

The lapse itself is not announced by email

You are emailed about each failed or unattempted charge, but no message today tells you the date your plan ends. Read the scheduled change on Plans for that date.

Renewal email is sent to your organization's billing email. If none is set, it goes to the organization owner instead, so the message still arrives. Set a billing email under Billing details to direct it somewhere specific.

Billing time and timezone

Billing periods, commitment allowances and daily or period limit resets are calculated from fixed UTC boundaries. Your timezone changes only how those instants are displayed; it never changes when a period starts, when usage resets, or how charges are calculated.

The Billing page therefore shows both:

1. the renewal instant converted to your IANA timezone, daylight-saving rules included; and
2. the canonical UTC boundary.

A boundary of 2026-08-20T00:00:00Z appears in Istanbul as Aug 20, 2026, 03:00 GMT+3, while the supporting line reads Aug 20, 2026, 00:00 UTC.

Periods are half-open

Usage at start_at belongs to the new period, while end_at is the first instant of the next period. A request at exactly the boundary lands in the period that is opening, never in the one that is closing.

API Reference

These endpoints back the Billing page. All require JWT authentication.

Endpoint	Method	Access
/api/v1/billing/wallet	GET	Admin or owner
/api/v1/billing/payg-spend-cap	GET	Any member
/api/v1/billing/payg-spend-cap	PUT, DELETE	Admin or owner
/api/v1/billing/documents/invoices	GET	Admin or owner
/api/v1/billing/documents/invoices/{id}	GET	Admin or owner
/api/v1/billing/documents/invoices/{id}/transactions	GET	Admin or owner
/api/v1/billing/documents/transactions	GET	Admin or owner
/api/v1/billing/commitment	GET	Admin or owner
/api/v1/billing/coupons/redeem	POST	Admin or owner
/api/v1/tenant-admin/billing-profile	GET, PATCH	Admin or owner
/api/v1/payments/limits	GET	Admin or owner
/api/v1/payments/checkout	POST	Admin or owner
/api/v1/payments/{intent_id}	GET	Admin or owner
/api/v1/payments/{intent_id}/cancel	POST	Admin or owner
/api/v1/payments/refundable	GET	Admin or owner

Requesting another organization's document returns 404, not 403

The API does not confirm that a document you cannot see exists. Treat 404 as "not yours or not there".

Wallet

curl https://api.bulutistan.ai/api/v1/billing/wallet \
  -H "Authorization: Bearer <your-jwt-token>"

Returns tenant_id, currency, total_balance, coupon_balance, topup_balance, settlement_credit_balance, promotional_balance, held_balance, held_reason, available_balance, unsettled_usage, effective_balance, wallet_mode, outstanding_debt, unbilled_accrual, total_outstanding, and a lots array.

• lots[] entries carry entry_type, remaining, expires_at (null when the lot never expires) and funding_source, listed in the exact order credit will be spent.
• total_balance equals the sum of lots[].remaining, and coupon_balance + topup_balance + settlement_credit_balance + promotional_balance equals total_balance. The headline never exceeds the rows beneath it.
• topup_balance counts card money only. Credit the platform granted you is reported separately as settlement_credit_balance, so the top-up figure can never read higher than what you were actually charged.
• held_balance is money currently reserved, with held_reason naming why. It counts both the short-lived hold taken while a request runs and a hold against an open payment dispute. available_balance is total_balance minus held_balance, and it is the figure requests are admitted against. total_balance does not move while a hold is in place. A request's hold expires by itself if it is never closed; a dispute hold never expires.
• effective_balance is available_balance minus unsettled_usage.
• wallet_mode is prepaid, postpaid or null. On a postpaid account unsettled_usage is the current-period accrual to be invoiced at period close, not a live deduction from your balance, and it is not the organization's debt. Read the three fields below for that.
• outstanding_debt is issued, unpaid documents net of payments, discounts, write-offs and credit notes. unbilled_accrual is delivered usage that no document bills yet, across every uninvoiced period, already netted of a plan's included allowance and a commitment's negotiated rates. total_outstanding is their sum, computed by the server — read it rather than adding the other two yourself.
• Any of the three may be null, meaning the figure could not be evaluated. Render null as unknown, never as 0.00 — telling a customer they owe nothing because a query failed is worse than showing nothing. They need no wallet_mode gate: a prepaid account reads 0.00 on all three by design, because its accrual is already inside unsettled_usage.
• All three are absent on a deployment that predates them. Treat an absent field the same as null.

Organization spending cap

# Read the current cap and period spend
curl https://api.bulutistan.ai/api/v1/billing/payg-spend-cap \
  -H "Authorization: Bearer <your-jwt-token>"

# Set or change it
curl -X PUT https://api.bulutistan.ai/api/v1/billing/payg-spend-cap \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"cap_usd": 500.00}'

# Remove it
curl -X DELETE https://api.bulutistan.ai/api/v1/billing/payg-spend-cap \
  -H "Authorization: Bearer <your-jwt-token>"

The request body carries exactly one field, cap_usd. It must be greater than zero with at most two decimal places; anything else is rejected with 422. There is no POST and no zero-cap: DELETE is the only way to remove a cap, and it is idempotent: it answers 200 with cap_usd: null whether or not a cap was set, never 404.

All three verbs return the same shape: tenant_id, limit_type (always payg_spend_cap), cap_usd, evaluated, period_id, period_start, period_end, period_track, period_spend_usd, period_audio_spend_usd, remaining_usd and exceeded.

Documents

curl "https://api.bulutistan.ai/api/v1/billing/documents/invoices?limit=50&offset=0" \
  -H "Authorization: Bearer <your-jwt-token>"

limit accepts 1–100 and defaults to 50. Draft documents are excluded from the list; voided documents are included.

An invoice carries id, tenant_id, billing_period_id, charge_type, source_id, invoice_number, status, currency, subtotal, total, amount_paid, remaining, related_invoice_id, issued_at, due_at, paid_at, voided_at, void_reason, notes, created_at and a lines array, plus the tax and bill-to block below.

Each line carries id, invoice_id, line_type, description, model_id, group_id, bucket, quantity, unit_price, price_source, amount, currency, period_start and period_end.

unit_price is now published on audio lines as well as token lines, with price_source of event_snapshot — the rate that was actually applied, per unit of that line's own quantity, so quantity × unit_price = amount. A unit billed at more than one rate during the period is returned as one line per rate. A rate that rounds to zero on a charged line is reported as null rather than as free.

Tax and bill-to fields: tax_rate, tax_amount, tax_inclusive, bill_to_legal_name, bill_to_tax_id, bill_to_country, bill_to_address, bill_to_email and bill_to_profile_completed_at.

• tax_amount is 0 and tax_rate is null on every document this platform issues. null means no rate was determined — it does not mean 0%.
• The bill_to_* fields are a snapshot taken when the document was issued and never change afterwards. They are null on documents issued before the fields existed.
• bill_to_profile_completed_at is null when the organization's billing profile had not been completed at issue time. A document is still issued and still payable in that state.

status is one of draft, issued, partially_settled, paid, void. charge_type is one of period_close, commitment_charge, subscription_fee, credit_note, manual. remaining is computed from what is still outstanding; total never moves.

curl "https://api.bulutistan.ai/api/v1/billing/documents/transactions" \
  -H "Authorization: Bearer <your-jwt-token>"

Accepts an optional transaction_type filter plus limit and offset. Each row carries id, tenant_id, transaction_type, amount, currency, source_type, source_id, invoice_id, description and created_at. transaction_type is one of invoice_issued, invoice_settlement, payment, payment_reversed, refund, credit_note, invoice_adjusted, discount_applied, coupon_redeemed, top_up, usage_summary, invoice_voided, credit_expired.

Classify by type, not by sign

payment_reversed is stored as a positive amount and is a charge — it restores debt. discount_applied is stored as a negative amount and is a credit. Deriving the direction from the sign gets both of them backwards. New types are added over time; treat an unrecognised one neutrally rather than guessing.

The per-invoice sub-path uses a different, narrower shape (id, kind, amount, note, created_at), where kind is payment, discount or payment_reversal.

Redeem a coupon

curl -X POST https://api.bulutistan.ai/api/v1/billing/coupons/redeem \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"code": "YOUR-COUPON-CODE"}'

The body carries code and nothing else. The code is matched case-insensitively with surrounding whitespace stripped, so there is nothing for a client to normalise: send what the customer typed. A code that is unknown, and a code scoped to another organization, are refused with the same 404 and the same message — do not branch on the wording to tell them apart.

Payments

Read the amount range the server accepts before offering the customer a field:

curl https://api.bulutistan.ai/api/v1/payments/limits \
  -H "Authorization: Bearer <your-jwt-token>"

Returns min_amount_minor, max_amount_minor and currency. Both bounds are configured per deployment — the lower one is the payment provider's own minimum and the upper one is the ledger's capture ceiling. Do not hard-code either.

The same response carries card_enabled. false means this deployment has no card provider at all and every checkout will be refused, so do not put a card payment in front of the customer. Read anything else as available, including an absent field: a deployment that predates the flag does not publish one. Like the bounds beside it, it is advisory. A provider disabled a moment after you read it still refuses the checkout, and the checkout call stays the authority.

Start a payment:

curl -X POST https://api.bulutistan.ai/api/v1/payments/checkout \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Idempotency-Key: <a key you generate, one per intent>" \
  -H "Content-Type: application/json" \
  -d '{"purpose": "wallet_topup", "amount_minor": 5000, "currency": "USD", "return_path": "/billing"}'

Field	Notes
purpose	wallet_topup, invoice_payment or plan_order
amount_minor	Integer minor units. For wallet_topup you choose it; for the other two it is verified against what the target actually owes.
target_ref	Required for invoice_payment (the invoice id) and plan_order (the order id); must be absent for wallet_topup
return_path	Relative path to come back to. An absolute or protocol-relative value is rejected.

The response carries a next_action naming the provider's hosted page. Follow it with a full browser redirect; there is no embedded card form.

Starting a checkout supersedes the organization's older payable sessions for the same purpose and target_ref, expiring them at the provider before the new one exists. There is never a moment with two payable pages for the same thing. The scope is per purpose and target, so paying an invoice while a wallet top-up is open leaves both alive — they are two legitimate payments. A next_action URL you cached from an earlier call may therefore point at a page that is now dead; always use the one from the response you are acting on.

Refusal	Meaning
422 amount_out_of_range	Outside the published bounds. The body repeats min_amount_minor and max_amount_minor.
422 billing_profile_incomplete	The organization's billing details are missing. The body names the required fields.
422 target_ref_required	A purpose that needs a target was sent without one
422 target_not_payable	The invoice is draft, void or already settled
422 target_amount_mismatch	The amount does not match what the target owes
409 idempotency_key_reuse_mismatch	The same key was reused with different terms
503 provider_unavailable	No card provider could take the payment. Read card_enabled on /payments/limits to tell a deployment that never takes cards apart from a provider that is momentarily unreachable

Send an Idempotency-Key, and reuse it on retries

Generate one key per payment intent and send it on every retry of that same intent. Replaying a key returns the original result and starts no second provider session. Minting a fresh key per attempt provides no protection at all — a reload mid-redirect would open a second session and both could charge.

Poll for the authoritative outcome; never treat the customer's arrival on your return page as proof of payment:

curl https://api.bulutistan.ai/api/v1/payments/{intent_id} \
  -H "Authorization: Bearer <your-jwt-token>"

Cancel a payment the customer walked away from:

curl -X POST https://api.bulutistan.ai/api/v1/payments/{intent_id}/cancel \
  -H "Authorization: Bearer <your-jwt-token>"

This is the call to make when the customer comes back through the provider's cancel door; keep using /return-ack for the success door. It asks the provider to expire the hosted session first and only mirrors the closure locally if that succeeded — so a payment that landed a second earlier is never reported back to the payer as one they abandoned.

{"intent_id": "...", "interaction_state": "expired",
 "provider_session_expired": true, "status": "no_facts", "captured_minor": 0}

Field	What it tells you
provider_session_expired	The only field to branch the promise on. true means the hosted page is closed at the provider and can no longer take a card.
interaction_state	Only that we closed our own record — which also happens when the provider could not be reached.
status, captured_minor	The real state of the money. A captured status means the page was paid; show the receipt and make no "nothing was charged" claim.

Branch on === true, never on truthiness. When provider_session_expired is anything else — refused by the provider, no session to expire, call failed or timed out — you may still say nothing has been charged, but not that nothing will be: tell the customer not to reuse the old link and to start again. An intent for another organization answers 404, never 403.

Cancelling never reverses a capture. That is a refund, a different authority.

And read the refund ceiling:

curl https://api.bulutistan.ai/api/v1/payments/refundable \
  -H "Authorization: Bearer <your-jwt-token>"

refundable_minor counts unspent card money only and is rounded down, so the figure it reports is always one a refund will accept. It is advisory, not a reservation — nothing is held.

Billing details

curl https://api.bulutistan.ai/api/v1/tenant-admin/billing-profile \
  -H "Authorization: Bearer <your-jwt-token>"

curl -X PATCH https://api.bulutistan.ai/api/v1/tenant-admin/billing-profile \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"billing_legal_name": "Example Ltd", "billing_country": "TR", "billing_email": "ap@example.com", "billing_address_line1": "1 Example Street"}'

The response reports whether the profile is complete and, when it is not, which fields are missing. billing_country is an ISO alpha-2 code. The completion timestamp is stamped once, on first completion, and is never cleared — clearing it would retroactively invalidate a payment that was legitimately allowed.

Commitment

curl https://api.bulutistan.ai/api/v1/billing/commitment \
  -H "Authorization: Bearer <your-jwt-token>"

Returns {"offer": …, "commitment": …}, either of which may be null. Commitments are negotiated contracts rather than self-service plans; if you have neither, both fields are null.