Billing, usage & caps¶

Where the numbers come from, how to read them, and how to fix a locked organization.

The screens¶

Screen	Shows
Usage	Cost this period, the breakdown by meter, and transaction history
Billing	Your plan, billing mode, balance, top-ups, payment method, and credit history

Both are organization-scoped and require the Admin role.

What's metered¶

On hosted storage, three meters fill your invoice:

Meter	Unit	Counts
Storage	MB-month	Retained artifact bytes, sampled over the period
Upload	MB	Artifact bytes successfully ingested
Download	MB	Artifact bytes served, to testers and developers

Storage is a rate over time: 1 GB held for half a month is about half a GB-month. That's why retention is the biggest lever you have on the storage line.

Download is usually the line that surprises people. A popular release multiplied by a large tester list moves a lot of bytes.

Failed and abandoned uploads are not billed. BYOSA organizations aren't metered at all — their cloud provider bills them directly.

Balance and top-ups¶

A pre-paid organization holds a balance: total credit minus charges.

Upload and download charges are deducted as they happen. Storage settles at the end of the billing period, so it isn't subtracted from your balance until then. If you're near zero, remember there's a storage charge still to land.

Add credit tops the balance up. Payment is handled by a third-party payment provider; AppGantry never sees or stores your card details.

Changing plans¶

Plan changes are API-only today

There is no plan switcher anywhere in the web app. Moving an organization between Team and Business is done by calling the API, or by asking support to do it for you. Nothing on the Billing screen changes a tier.

An organization moves between Team and Business through POST /api/v1/organizations/{organization_id}/tier, with the target plan in the body. Two things are required together:

the organization Admin role, and
a credential carrying the full-capability ALL scope.

An interactive admin session qualifies. So does an admin's personal access token minted with ALL — this is not one of the surfaces that refuses long-lived tokens, so a PAT is genuinely accepted here. Any narrower scope is refused, because changing how you are billed is a privileged write rather than a routine one.

The web app's token screen cannot mint an ALL-scoped PAT: it offers one checkbox per named scope and the composite is deliberately not among them. Create that token over the API if you want to script a tier change.

The call has two outcomes:

Outcome	When	What happens
`changed`	A downgrade, or an upgrade of an organization that already has a card on file	The plan changes immediately and the response reports the new tier
`checkout_required`	An upgrade to Business with no card on file	The plan is unchanged and the response carries a card-capture checkout to open

Business is pre-paid exactly like Team — usage still draws down your balance — but its higher monthly platform fee is charged in advance, so a card has to be captured before the upgrade can complete. Handle checkout_required by opening the returned checkout; treat the plan as unchanged until you confirm it.

Two requests are refused rather than being no-ops worth retrying: asking for the plan the organization is already on, and any tier change on a BYOSA organization.

What changes with the plan: SSO and BYOSA eligibility, and the default retention windows. What doesn't: your projects, builds, releases, testers, tokens and audit history. Downgrading a Business organization that has SSO configured leaves the connection in place but no longer eligible — disabling SSO is always allowed, so a downgraded organization can still turn it off. See Plans & pricing and Single sign-on.

Payment methods¶

The Payment method card is where you add, replace, or subscribe with a card. What it says depends on your state:

No card, on a trial → Subscribe now.
No card, otherwise → Add payment method.
Card on file → Update payment method, which replaces it.

Payment setup can be unavailable

In some environments online payment setup is switched off, and the page says so and points you at support. That's a property of the deployment, not a fault on your account. See Feature availability.

Payment emails link to a checkout page, not the app¶

When a payment needs finishing — a card that failed, a payment-method update requested by the payment provider — the email links to a small AppGantry page whose only job is to open the provider's checkout for that transaction. It lives at https://app.appgantrystaging.com/pay on the same host as the rest of the app, so the link you are asked to trust is the host you already sign in to. Check that before you click: a payment prompt from any other domain is not ours.

It is a payment page, not a sign-in page: it asks for no password, shows none of your account data, and works whether or not you're signed in.

Finishing the payment there clears the charge. Nothing else about the organization is changed from that page, so come back to Billing for balance, plan, or spend-cap changes.

Spend caps¶

An organization can set a monthly spend cap, made up of your own self-limit and an account ceiling; the lower one applies. Reaching it returns HTTP 402 on uploads and downloads while leaving all metadata readable.

Spend caps are an API-level control today — there's no dedicated screen. Read and set one with:

Operation	Route
Read the current cap	`GET /api/v1/organizations/{organization_id}/spend-cap`
Set or clear the cap	`PUT /api/v1/organizations/{organization_id}/spend-cap`

Both require organization Admin. Request and response shapes are in the interactive API reference. See Audit & spend caps.

When writes are blocked, and how to clear it¶

An organization can be blocked from writing while staying fully readable. The API reports HTTP 402; the web app shows a banner. There are two different reasons that happens, and they behave differently.

Organization write locks. The organization is in a billing state that blocks all writes, and the 402 carries details.lock_reason:

State	`error` code	`lock_reason`	Cause	Fix
Awaiting payment	`payment_required`	`awaiting_payment`	Committed to a paid plan, no card captured yet	Add a payment method
Suspended	`billing_suspended`	`suspended`	Payment problems went unresolved	Settle the balance
Trial ended	`trial_ended`	`grace`	The no-card trial ran out of time and no card was added	Add a payment method

A card that is currently failing is not one of these. While the payment provider is still retrying — past due, dunning in progress — the organization keeps writing normally; it only locks once the retries are exhausted and it becomes suspended.

Per-request billing gates. The organization isn't locked; the individual request was refused. These carry no lock_reason:

State	`error` code	Cause	Fix
Prepaid exhausted	`prepaid_credit_exhausted`	Balance at zero. A trial that burns through its starter credit lands here too	Top up, or add a payment method if you're on a trial
Spend cap reached	`spend_cap_exceeded`	You hit your own ceiling	Raise or clear the cap, or wait for the next period

In every case:

Your organization, projects, builds, testers, and audit history stay intact and readable.
Under suspended, downloads of existing builds keep working for a configured period, so your testers aren't cut off the instant a card expires.
Under trial ended, uploads, downloads, and organization-scoped writes are all refused until a payment method is added.
Nothing is deleted for non-payment as part of the lock.

See Errors → 402 for the canonical taxonomy.

Keeping the bill predictable¶

Shorten retention if storage is the big line. It's the single most effective change.
Set a spend cap at a few times your normal spend.
Check Usage when you ship something you expect to be popular.
Be careful with public channels. Anonymous downloads meter exactly like tester downloads.
Prune old builds you'll never install again.
Consider BYOSA if egress consistently dominates. It replaces per-MB metering with a flat fee plus your own cloud bill.

What isn't billed¶

Members. Add as many as you like.
Testers. Their downloads are metered; their existence isn't.
Projects and channels.
API calls, webhooks, and audit reads.
Failed or abandoned uploads.

AppGantry bills for bytes, not seats. Never share a login to save money: you lose the audit trail that tells you who did what, and it saves you nothing.