Billing

The billing account behind an enterprise: the plan and subscription state, the invoices raised against it per billing period, and the usage counted over a window you choose.

Every field here is a query. There are no billing mutations on the Enterprise API.

All three queries are scoped to the enterprise the token acts for — none of them takes an enterprise argument — and all three require enterprise:billing:read.

Current billing info

billingInfo takes no arguments and is non-null: it returns a plan or it errors.

FieldMeaning
planName
The subscribed plan, as a display string
monthlyCost
Recurring cost of the plan
billingCycle
MONTHLY, QUARTERLY or ANNUALLY
subscriptionStatus
ACTIVE, TRIALING, PAST_DUE, UNPAID or CANCELED
currentPeriodStart / currentPeriodEnd
Bounds of the period being accrued
nextBillingDate
When the next charge falls due
enterpriseId / enterpriseName
The account these figures belong to

billingCycle tells you how often the account is charged, which is not necessarily monthly. monthlyCost is the only cost field on billingInfo — for what was actually charged, read an invoice.

monthlyCost is a bare Float with no currency beside it — currency exists on an invoice, not on billingInfo. Read the currency from a recent invoice rather than assuming one from the account's country.

currentPeriodStart, currentPeriodEnd and nextBillingDate are typed String, not DateTime, so a generated client will hand you a plain string. Only the field descriptions say RFC 3339; the type does not enforce it. The same is true of every date on an invoice and on a usage summary.

Invoices

invoices is cursor-paginated in both directions — first/after forwards, last/before backwards — and returns newest first. totalCount is the number of invoices on the account, ignoring pagination. See Pagination for the cursor rules.

Each invoice carries both id (the row) and invoiceId (the formatted invoice number) — quote the latter to a customer, key on the former.

FieldMeaning
status
DRAFT, OPEN, PAID, VOID or UNCOLLECTIBLE
billingPeriodStart / billingPeriodEnd
The period the invoice covers
dueDate
When payment is due
paidDate
When it was paid; null until then
subtotal, taxAmount, totalAmount
Amounts, in currency
lineItems
description, quantity, unitPrice, total per line

paidDate is the only nullable field on an invoice; every other field is non-null, including dueDate on a DRAFT invoice.

invoices takes no filter arguments — only the four cursor arguments — so narrowing to a status or a date range is done on your side, over the pages you have walked.

Line items are returned in full with the invoice; there is no separate query for them and no pagination over them.

Usage for a period

usageSummary counts activity over an explicit window. Both periodStart and periodEnd are required DateTime arguments — there is no all-time variant, and no default period.

What comes back is volume, not spend: headcount, vouchers created and redeemed, API calls, webhook deliveries and storage in megabytes. No field on it is monetary, so it reconciles an invoice rather than predicting one — pass the billingPeriodStart and billingPeriodEnd of an invoice to see what was counted underneath it.

The arguments are DateTime, but periodStart and periodEnd come back on the summary as String.

Reference

Generated reference — every type, field and argument, built from the live schema.

Built with