Docs
⌘K
Billing ›

Get billing

GET/v1/billing

Where the account stands: its plan, the month's usage, what is left.

RequestTypeScript
  1. import { Agental } from "agental-sdk";
  3. const agental = new Agental();
  4. const billing = await agental.billing();
Answer200 OK · Billing
  1. {
  2. "provider": "stripe" | "not_configured",
  3. "testMode": boolean,
  4. "enforced": boolean,
  5. "needsPlan": boolean,
  6. "status": "none" | "trialing" | "active" | "past_due" | "paused" | "canceled",
  7. "plan": {
  8. "id": string,
  9. "dollarsPerMonth": integer,
  10. "includedMicros": integer,
  11. "runningUnits": integer,
  12. "freeBurstUnits": integer,
  13. "sandboxesAtOnce": integer,
  14. … 2 more
  15. },
  16. "period": {
  17. "start": string,
  18. "end": string,
  19. },
  20. "free": {
  21. "cardSaved": boolean,
  22. "paid": boolean,
  23. "unpaidUnits": integer,
  24. },
  25. "includedMicros": integer,
  26. … 15 more
  27. }

Where the caller's account stands: its plan, what it has used of the month, what is left of its top-ups, and whether it may run a sandbox.

Headers

Authorizationrequired
Bearer key
An API key that may make this call.

Returns

200 Where the caller's account stands: its plan, what it has used of the month, what is left of its top-ups, and whether it may run a sandbox. Amounts are millionths of a US dollar.

Billing24 fields
provider
stripenot_configured
Who sells here.
More stripe: plans and top-ups are bought from agental, through Stripe. not_configured: nothing can be bought.
testMode
boolean
True while the payment provider is in its test mode: nothing is really charged.
enforced
boolean
Whether a plan is needed to run a sandbox.
More False: plans are shown and sold, and nothing is held to them.
needsPlan
boolean
True while this account must save a card, or buy a plan, before it uses agental: plans are enforced here, and it is on the free plan with no card saved.
More The console shows that choice before anything else while it is.
status
nonetrialingactivepast_duepausedcanceled
The subscription to a plan bought by the month, as the payment provider names it.
More none or canceled: the account is on the free plan.
plan
objectnull8 fields
The plan the account is on: one bought by the month while it is live, else the free plan.
More Null where plans are not enforced on it and it has none bought.
id
string
dollarsPerMonth
integer
includedMicros
integer
runningUnits
integer
Small sandboxes the plan runs at once.
More A medium counts 2, a large 4, a tiny half. A create, fork or start past it is refused with 429 running_limit_reached.
freeBurstUnits
integer
Small sandboxes the plan starts at once for nothing, counted as runningUnits is.
More Starting faster costs a burst fee: see burstFee, and GET /v1/burst for an account's own.
sandboxesAtOnce
integer
The same as runningUnits: small sandboxes the plan runs at once.
More Sent for clients that read it, and it will be removed.
burst
object3 fields
Kept for clients that read it: the free burst in megabytes.
More Nothing is refused for speed now; a start faster than the free burst costs a fee.
tier
integer
The plan's place among the plans, 0 for the free plan.
perQuarterMb
integer
The plan's free burst, in megabytes: freeBurstUnits times 4096.
perHourMb
integer
The same as perQuarterMb.
sizes
string[]
period
objectnull2 fields
The month the plan is in.
More On the free plan, from where its use was last settled against its credits to the next month's start, in UTC.
start
string
end
string
free
objectnull3 fields
Set while the account is on the free plan.
cardSaved
boolean
Whether the account has a card saved, which it must before it runs anything, and so has had its credit.
paid
boolean
Whether it has paid for anything.
More Until it has, it runs and starts at most unpaidUnits small sandboxes at once.
unpaidUnits
integer
includedMicros
integer
usedMicros
integer
What has been used this month at list price: running time, mail, stopped sandboxes and snapshots past the free ones.
discount
object3 fields
Retired: bigger top-ups get a bonus instead.
More Always 0, 0 and null, sent for clients that read it.
micros
integer
percent
number
next
objectnull2 fields
fromMicros
integer
percent
number
mailMicros
integer
The part of usedMicros that is mail: 500 a message, received or sent, which is $0.50 a thousand.
stoppedMicros
integer
The part of usedMicros that is stopped sandboxes, at 5% of their running price, or 10% while one keeps its memory.
snapshotMicros
integer
The part of usedMicros that is snapshots past the free ones.
burstMicros
integer
The part of usedMicros that is burst fees: what starts faster than the plan's free burst cost.
More GET /v1/burst says where the account stands.
carriedMicros
integer
What an earlier month ran past its plan and its top-ups.
More This month's credits pay it first, then the top-ups. On the free plan, what the account owes now: what it has run past its credits.
topUpMicros
integer
What is left of the credits bought on top of the plan, and of the free plan's credit.
More It is used after the month's credits, and it does not expire.
sandboxesAtOnce
integernull
The same as runningUnits: small sandboxes the plan runs at once.
More Sent for clients that read it, and it will be removed.
cancelAtPeriodEnd
boolean
canRun
boolean
reason
billing_requiredout_of_creditnullnull
autoReload
objectnull1 field
The auto-reload: when the month's credits and the top-ups run out, the card saved at the last purchase is charged for a top-up of this many US dollars, with tax, and its credits are added at once, before any sandbox is stopped.
More Null while it is off. Set with PUT /v1/billing/auto-reload.
dollars
integer
The top-up charged, in whole US dollars.
canAutoReload
boolean
Whether an auto-reload can be set: Stripe sells here, and the account has saved a card there, or bought a plan or a top-up.
lapse
objectnull3 fields
Set while the account has no card saved, or has used its credits, and still holds sandboxes or snapshots.
More The account is emailed when it begins, 7 days before deletesAt and the day before; the account itself stays open. A top-up that pays what is owed, a card saved, a plan started, or deleting everything ends it. Null otherwise, and always where plans are not enforced.
reason
no_planunpaidout_of_credit
no_plan: the account is on the free plan with no card saved.
More out_of_credit: it is on the free plan and its credits are used. unpaid: it has a plan bought by the month and owes for what it used past the plan's credits and its top-ups, from a month that has closed.
lapsedAt
string
When the account was first seen with no plan, or owing, while it held sandboxes or snapshots.
deletesAt
string
When its sandboxes and snapshots are deleted, with the mail they received, unless what is owed is paid, a card saved or a plan started first.
More 30 days after lapsedAt.
← List billing plansCreate billing checkout →