billing

Billing tells an organization what it spends, on what, and who spent it: usage recorded on meters is priced from a rate card per billing account and month, then shared out to the people, agents, teams, departments and projects that produced it. Budgets alert and can refuse usage, and the platform issues monthly invoices (statements) with credit applied. Invoicing works like Stripe or Orb: drafts, finalized, paid, uncollectible and void invoices; one-off invoice items; payments and credit notes; plans with fees, seats and meter prices; subscriptions with trials and prorations; coupons; payment reminders and a printable invoice. Server code records usage, takes payments and runs the jobs through iam.billing (no credential). The repository guide is docs/billing.md.

How spend is computed

A billing account is an organization, or a tenant below it with a billing profile of its own. For each account and month, every meter's total is priced once (tiers and free units apply to the account's total), and the cost is shared out to the daily roll-ups of usage by quantity; for unique meters every person or agent costs the same. Reported meters carry their own cost per event. Person, team, department and project spend therefore add up to the account's charges. Meters an account defines for itself are chargeback only (internal) and never appear on a statement.

Usage is attributed when it is recorded: the identity, its direct teams (split evenly by default, see the billing option teamAttribution), and its department (or its first team's). An agent's usage counts toward its sponsor's teams and department. Money is in micros of the deployment currency (costMicros), with rounded amount fields in currency units.

Permissions

iam:billing:read reads spend, budgets, credits, profiles, invoices, plans, subscriptions and discounts; iam:billing:manage defines meters and prices in the tenant, budgets and profiles, and lets an account's billing managers subscribe to self-serve plans and redeem coupon codes; iam:billing:record records usage. Resources are iam/billing, iam/billing/meters/{key}, iam/billing/budgets, iam/billing/profile, iam/billing/credits, iam/billing/statements, iam/billing/invoice-items, iam/billing/plans, iam/billing/subscriptions, iam/billing/coupons and iam/billing/discounts. Credits, closing a month, invoice items, payments, credit notes, plans and coupons are for root administrators only; they act on any account's invoice by calling on the root tenant.

accounts

Lists the billing accounts in the tenant's subtree with this month's billable spend, projection, available credit and latest statement.

• Permission: iam:billing:read on iam/billing.
• Audited as: iam:billing:read.

On the root tenant this is every organization: the platform's receivables view. monthToDateMicros counts only meters defined above the account (what a statement would bill); totalMicros includes the account's own chargeback meters.

curl -X POST "$IAM_URL/api/iam/billing/accounts" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.billing.accounts(
  credential: CredentialInput,
  input: { tenantId: string },
): Promise<AccountOverview[]>

anomalies

Lists the people, teams and meters whose spend on one day jumped far above their usual daily spend.

• Permission: iam:billing:read on iam/billing.
• Audited as: iam:billing:read.
• Errors: INVALID_INPUT for a malformed day, baselineDays outside 3 to 90, factor outside 1.1 to 1000, or a negative minimum.

day defaults to yesterday in the billing time zone. A spike is spend at least factor (3) times the average over the baselineDays (14) before it and at least minimum (10 currency units) more; spending with no baseline counts when it reaches minimum (factor: null). The largest increases come first, at most 50. The daily job iam.billing.detectAnomalies() alerts on them once each (billing:anomaly, spend-anomaly email).

const { anomalies } = await iam.api.billing.anomalies(admin, { tenantId, factor: 5 });

curl -X POST "$IAM_URL/api/iam/billing/anomalies" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.billing.anomalies(
  credential: CredentialInput,
  input: { tenantId: string } & AnomalyOptions,
): Promise<{ tenantId: string; anomalies: SpendAnomaly[] }>

cancelSubscription

Cancels a subscription at the end of the month (default) or now.

• Permission: iam:billing:manage on iam/billing/subscriptions (self-serve plans, at the month's end only), or a root administrator.
• Audited as: billing:subscription-cancel.
• Errors: ACCESS_DENIED (403) for an immediate cancellation by anyone but a root administrator; INVALID_TRANSITION (409) for an ended subscription.

At the month's end the subscription keeps running and resumeSubscription can undo it. With atPeriodEnd: false it ends now and the unused part of this month's advance fees and seats is credited as invoice items; arrears items bill the part of the month it ran.

curl -X POST "$IAM_URL/api/iam/billing/cancelSubscription" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "subscriptionId": "<subscriptionId>"
}'

iam.api.billing.cancelSubscription(
  credential: CredentialInput,
  input: { tenantId: string; subscriptionId: string; atPeriodEnd?: boolean },
): Promise<{ subscription: SubscriptionView; invoiceItems: InvoiceItemView[] }>

changePlan

Moves a subscription to another plan now, keeping its seats and what is left of its trial.

• Permission: iam:billing:manage on iam/billing/subscriptions when both plans are self-serve, or a root administrator.
• Audited as: billing:subscription-plan-change.
• Errors: CONFLICT (409) when the account already subscribes to the new plan; INVALID_TRANSITION (409) for an ended subscription or an archived plan; INVALID_INPUT for the same plan.

The old subscription ends and a new one starts. The old plan's unused advance charges are credited and the new plan's charges for the rest of the month added, both as invoice items for the next invoice (invoiceItems).

curl -X POST "$IAM_URL/api/iam/billing/changePlan" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "subscriptionId": "<subscriptionId>",
  "plan": "<plan>"
}'

iam.api.billing.changePlan(
  credential: CredentialInput,
  input: { tenantId: string; subscriptionId: string; plan: string },
): Promise<{ subscription: SubscriptionView; invoiceItems: InvoiceItemView[] }>

check

Reports whether the caller's own usage is within every enforced budget that covers it.

• Permission: The caller's own session; the tenant must be the caller's tenant or one below it.
• Audited as: not audited.
• Errors: ACCESS_DENIED (403) for a tenant outside the caller's.

Covering budgets are enforced tenant budgets on the tenant or an ancestor, and the caller's own, their teams' (with parent teams) and their department's (with the departments above it); meter narrows to budgets that count it. blockedBy names the first spent budget. Statuses may lag recorded usage by up to 30 seconds. Server code checks any identity with iam.billing.check.

const verdict = await client.billing.check({ tenantId, meter: 'api-calls' });
if (!verdict.allowed) showBudgetBanner(verdict.blockedBy);

curl -X POST "$IAM_URL/api/iam/billing/check" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.billing.check(
  credential: CredentialInput,
  input: { tenantId: string; meter?: string },
): Promise<SpendCheck>

closePeriod

Issues statements for a month that has ended, for every billing account or only accountId's.

• Permission: Root administrators only, called on the root tenant (iam:billing:manage on iam/billing/periods).
• Audited as: iam:billing:manage; each statement as billing:statement.
• Errors: INVALID_INPUT for the current or a future month, or when called on another tenant.

period defaults to last month. Each invoice bills the month's usage of platform meters, the subscriptions' fees and seats (the month itself for arrears items, the next month for advance ones), and pending invoice items. Accounts already invoiced for the month and accounts with nothing to bill are skipped (skipped.existing, skipped.empty), so the job is safe to repeat. Coupons apply after the contract discount, credit earliest expiry first; invoices are emailed (billing-statement) to the profile's billing emails or the owners, and raw usage events past their retention are deleted (sweptUsage). With draft: true (or the option billing.autoFinalize: false) invoices are kept as drafts, refreshed on every run, and listed in drafted; finalize them with finalizeInvoice. Schedulers call iam.billing.closePeriod() instead.

curl -X POST "$IAM_URL/api/iam/billing/closePeriod" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.billing.closePeriod(
  credential: CredentialInput,
  input: { tenantId: string; period?: string; accountId?: string; draft?: boolean },
): Promise<ClosePeriodResult>

createBudget

Creates a spend budget for the tenant, a tenant below it, a team, a department or a person, per month, quarter or year.

Used inBilling and spend

• Permission: iam:billing:manage on iam/billing/budgets.
• Audited as: billing:budget-create.
• Errors: CONFLICT (409) for a name already used (case-insensitive); LIMIT_EXCEEDED (409) past 200 budgets; NOT_FOUND for a subject outside the tenant; INVALID_INPUT for an amount of 0, a malformed meter key, more than 10 thresholds or notification addresses.

amount is in currency units. thresholds (default 50, 80, 100 percent) and forecastAlerts (default on) drive the alerts that iam.billing.checkBudgets() sends once per window to the owners, the subject (the person, the team's maintainers or the department head) and notify.emails. enforce makes covered usage fail once the budget is spent. The result is the budget with its current standing.

await iam.api.billing.createBudget(admin, {
  tenantId,
  name: 'Platform team monthly',
  subjectType: 'team',
  subjectId: platformTeamId,
  amount: 600,
  notify: { emails: ['finance@acme.test'] },
});

curl -X POST "$IAM_URL/api/iam/billing/createBudget" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "name": "<name>",
  "amount": 1
}'

iam.api.billing.createBudget(
  credential: CredentialInput,
  input: { tenantId: string } & BillingBudgetInput,
): Promise<BillingBudgetView>

createCoupon

Creates a coupon accounts can redeem by code.

• Permission: Root administrators only (iam:billing:manage on iam/billing/coupons), called on the root tenant.
• Audited as: billing:coupon.
• Errors: CONFLICT (409) for a code already used; INVALID_INPUT for a code that is not 3 to 32 letters, digits, - or _, both or neither of percentOff and amountOff, a percentage outside 0 to 100, durationInMonths without duration: 'repeating', or a redeemBy in the past.

Codes are stored in upper case. duration is once (default: the next invoice), repeating (invoices for durationInMonths months from the month of redemption) or forever. maxRedemptions caps how many accounts may redeem it.

await iam.api.billing.createCoupon(root, {
  tenantId: rootTenantId,
  code: 'LAUNCH20',
  percentOff: 20,
  duration: 'repeating',
  durationInMonths: 3,
});

curl -X POST "$IAM_URL/api/iam/billing/createCoupon" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "code": "<code>"
}'

iam.api.billing.createCoupon(
  credential: CredentialInput,
  input: {
    tenantId: string;
    code: string;
    name?: string;
    percentOff?: number;
    amountOff?: number;
    duration?: BillingCoupon['duration'];
    durationInMonths?: number;
    maxRedemptions?: number;
    redeemBy?: number;
  },
): Promise<CouponView>

createCreditNote

Issues a credit note against a finalized, paid or uncollectible invoice.

• Permission: Root administrators only (iam:billing:manage on iam/billing/statements).
• Audited as: billing:credit-note.
• Errors: INVALID_INPUT for an amount above what is left to credit, an unknown reason, or a non-boolean refund; INVALID_TRANSITION (409) for a draft or void invoice.

amount defaults to everything not yet credited. The note first reduces the amount due; the rest (a part already paid) becomes account credit, or with refund: true is recorded as refunded outside Better IAM. applied shows the split. Notes are numbered {invoice}-CN-01, -CN-02, ...; reason is duplicate, fraudulent, order_change, product_unsatisfactory or other (default), with an optional memo. An invoice the notes and payments cover is paid.

curl -X POST "$IAM_URL/api/iam/billing/createCreditNote" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "statementId": "<statementId>"
}'

iam.api.billing.createCreditNote(
  credential: CredentialInput,
  input: {
    tenantId: string;
    statementId: string;
    amount?: number;
    reason?: BillingCreditNote['reason'];
    memo?: string;
    refund?: boolean;
  },
): Promise<{ statement: StatementSummary; creditNote: CreditNoteView }>

createInvoiceItem

Adds a one-off charge, or with a negative amount a credit, to the billing account's next invoice.

• Permission: Root administrators only (iam:billing:manage on iam/billing/invoice-items), called on the account.
• Audited as: billing:invoice-item.
• Errors: INVALID_INPUT when the tenant is not a billing account, for an empty description, an amount beyond one billion, a quantity of 0, or more than 20 metadata entries; BILLING_PERIOD_CLOSED (409) for a period already invoiced.

amount is per unit in currency units and quantity defaults to 1; the item's total is rounded to the cent. period bills it on the invoice for that month instead of the next one. When credit items exceed an invoice's charges the invoice totals 0 and the rest becomes account credit.

await iam.api.billing.createInvoiceItem(root, {
  tenantId: acmeId,
  description: 'Onboarding workshop',
  amount: 500,
});

curl -X POST "$IAM_URL/api/iam/billing/createInvoiceItem" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "description": "<description>",
  "amount": 1
}'

iam.api.billing.createInvoiceItem(
  credential: CredentialInput,
  input: {
    tenantId: string;
    description: string;
    amount: number;
    quantity?: number;
    period?: string;
    metadata?: Record<string, string>;
  },
): Promise<InvoiceItemView>

createMeter

Defines a usage meter: a platform meter on the root tenant, a chargeback meter for the tenant's subtree elsewhere.

Used inBilling and spend

• Permission: iam:billing:manage on iam/billing/meters/{key}.
• Audited as: billing:meter-create.
• Errors: CONFLICT (409) when a meter with the key already reaches the tenant; LIMIT_EXCEEDED (409) past 100 meters; INVALID_INPUT for a malformed key or a unique reported meter.

Keys are 1 to 64 lowercase letters, digits, dots, underscores or hyphens, starting with a letter. aggregation is sum (default) or unique (distinct people and agents per month); pricing is rate-card (default) or reported (each event carries its cost). Neither can change later.

curl -X POST "$IAM_URL/api/iam/billing/createMeter" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "key": "<key>",
  "name": "<name>"
}'

iam.api.billing.createMeter(
  credential: CredentialInput,
  input: {
    tenantId: string;
    key: string;
    name: string;
    unit?: string;
    description?: string;
    aggregation?: BillingMeter['aggregation'];
    pricing?: BillingMeter['pricing'];
  },
): Promise<MeterView>

createPlan

Defines a plan on the platform (root) tenant.

Used inBilling and spend

• Permission: Root administrators only (iam:billing:manage on iam/billing/plans), called on the root tenant.
• Audited as: billing:plan.
• Errors: CONFLICT (409) for a key already used; LIMIT_EXCEEDED (409) past 100 plans; INVALID_INPUT for a malformed key, 0 or more than 20 items, duplicate item ids, two items pricing one meter, or a malformed price.

items are fee (amount per month), seat (unitAmount per seat and month, includedSeats), both billed in advance (default) or arrears, and usage (meter with a price that replaces the rate card for subscribers). trialDays (1 to 365) starts subscriptions with a free trial; selfServe lets account billing managers subscribe.

await iam.api.billing.createPlan(root, {
  tenantId: rootTenantId,
  key: 'team',
  name: 'Team',
  selfServe: true,
  items: [
    { id: 'platform', kind: 'fee', name: 'Platform fee', amount: 99 },
    { id: 'seats', kind: 'seat', name: 'Seats', unitAmount: 12, includedSeats: 3 },
  ],
});

curl -X POST "$IAM_URL/api/iam/billing/createPlan" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "key": "<key>",
  "name": "<name>",
  "items": [
    {}
  ]
}'

iam.api.billing.createPlan(
  credential: CredentialInput,
  input: {
    tenantId: string;
    key: string;
    name: string;
    items: unknown[];
    description?: string;
    trialDays?: number;
    selfServe?: boolean;
  },
): Promise<PlanView>

deactivateCoupon

Stops a coupon (by code) from being redeemed; accounts that redeemed it keep their discount.

• Permission: Root administrators only (iam:billing:manage on iam/billing/coupons), called on the root tenant.
• Audited as: billing:coupon-deactivate.
• Errors: NOT_FOUND for an unknown code.

curl -X POST "$IAM_URL/api/iam/billing/deactivateCoupon" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "code": "<code>"
}'

iam.api.billing.deactivateCoupon(
  credential: CredentialInput,
  input: { tenantId: string; code: string },
): Promise<CouponView>

deleteBudget

Deletes a budget and its alert history.

• Permission: iam:billing:manage on iam/billing/budgets.
• Audited as: billing:budget-delete.
• Errors: NOT_FOUND for a budget of another tenant.

curl -X POST "$IAM_URL/api/iam/billing/deleteBudget" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "budgetId": "<budgetId>"
}'

iam.api.billing.deleteBudget(
  credential: CredentialInput,
  input: { tenantId: string; budgetId: string },
): Promise<{ success: true }>

deleteInvoiceItem

Deletes a pending invoice item.

• Permission: Root administrators only (iam:billing:manage on iam/billing/invoice-items), called on the account.
• Audited as: billing:invoice-item-delete.
• Errors: INVALID_TRANSITION (409) for an item already on a finalized invoice (issue a credit note instead).

curl -X POST "$IAM_URL/api/iam/billing/deleteInvoiceItem" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "itemId": "<itemId>"
}'

iam.api.billing.deleteInvoiceItem(
  credential: CredentialInput,
  input: { tenantId: string; itemId: string },
): Promise<{ success: true }>

deleteMeter

Deletes a meter that has never recorded usage, with its prices.

• Permission: iam:billing:manage on iam/billing/meters/{key}.
• Audited as: billing:meter-delete.
• Errors: RESOURCE_IN_USE (409) once the meter has recorded usage (archive it with updateMeter instead); NOT_FOUND when the tenant does not define the key.

curl -X POST "$IAM_URL/api/iam/billing/deleteMeter" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "key": "<key>"
}'

iam.api.billing.deleteMeter(
  credential: CredentialInput,
  input: { tenantId: string; key: string },
): Promise<{ success: true; removedPrices: number }>

deleteProfile

Removes a billing profile, so the tenant's usage rolls into its parent's account again.

• Permission: iam:billing:manage on iam/billing/profile; below an organization, called from an ancestor with targetTenantId.
• Audited as: billing:profile-delete.
• Errors: NOT_FOUND without a profile; ACCESS_DENIED (403) when a tenant below an organization removes its own.

curl -X POST "$IAM_URL/api/iam/billing/deleteProfile" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.billing.deleteProfile(
  credential: CredentialInput,
  input: { tenantId: string; targetTenantId?: string },
): Promise<{ success: true }>

departmentSpend

Reports a department's spend, with the departments below it, grouped by identity by default.

• Permission: The department's head (or the head of a department above it), or iam:billing:read.
• Audited as: iam:billing:read, with metadata.via department-head or permission.
• Errors: ACCESS_DENIED (403) for anyone else; NOT_FOUND for a department outside the tenant.

curl -X POST "$IAM_URL/api/iam/billing/departmentSpend" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "departmentId": "<departmentId>"
}'

iam.api.billing.departmentSpend(
  credential: CredentialInput,
  input: {
    tenantId: string;
    departmentId: string;
    period?: string;
    groupBy?: SpendGroupBy;
  },
): Promise<SpendReport>

exportSpend

Returns a spend report as a CSV file: one row per group with the amount, share, events and a column per meter's quantity.

• Permission: iam:billing:read on iam/billing.
• Audited as: iam:billing:read.
• Errors: as spend.

It takes the same input as spend and returns filename, contentType and body (RFC 4180, CRLF line endings, a final total row). Cells that a spreadsheet would run as a formula are prefixed with a quote.

curl -X POST "$IAM_URL/api/iam/billing/exportSpend" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.billing.exportSpend(
  credential: CredentialInput,
  input: { tenantId: string } & SpendQuery,
): Promise<CsvExport>

exportStatement

Returns a statement as a CSV file: its lines, credit and total, then the breakdown by project, team, department and person.

• Permission: iam:billing:read on iam/billing/statements; the statement's account must be the tenant or below it.
• Audited as: iam:billing:read.
• Errors: NOT_FOUND for a statement outside the tenant's subtree.

The file is named after the statement number. Department rows carry their cost center.

curl -X POST "$IAM_URL/api/iam/billing/exportStatement" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "statementId": "<statementId>"
}'

iam.api.billing.exportStatement(
  credential: CredentialInput,
  input: { tenantId: string; statementId: string },
): Promise<CsvExport>

finalizeInvoice

Finalizes a draft invoice: recomputes it with the latest usage and invoice items, numbers it, seals it and emails it.

• Permission: Root administrators only (iam:billing:manage on iam/billing/statements), called on the account or the root tenant.
• Audited as: billing:statement-finalize and billing:statement.
• Errors: INVALID_TRANSITION (409) for an invoice that is not a draft, or a draft with nothing left to bill.

The invoice then consumes its credit, marks its invoice items invoiced, its subscriptions' advance months billed, and its coupons used. An invoice with nothing to pay is paid on issue.

curl -X POST "$IAM_URL/api/iam/billing/finalizeInvoice" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "statementId": "<statementId>"
}'

iam.api.billing.finalizeInvoice(
  credential: CredentialInput,
  input: { tenantId: string; statementId: string },
): Promise<StatementSummary>

getProfile

Returns the billing profile of the tenant (or of targetTenantId below it) and the account that pays for it.

• Permission: iam:billing:read on iam/billing/profile.
• Audited as: iam:billing:read.

account.inherited is true when an ancestor pays; profile is null without a profile of its own.

curl -X POST "$IAM_URL/api/iam/billing/getProfile" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.billing.getProfile(
  credential: CredentialInput,
  input: { tenantId: string; targetTenantId?: string },
): Promise<ProfileView>

getStatement

Returns one statement with its lines, credit, breakdown and bill-to details, re-checking its content hash.

• Permission: iam:billing:read on iam/billing/statements; the statement's account must be the tenant or below it.
• Audited as: iam:billing:read.
• Errors: NOT_FOUND for a statement outside the tenant's subtree.

verified is false when the stored content no longer matches the hash computed at issue. overdue is true for a finalized statement past its due date.

curl -X POST "$IAM_URL/api/iam/billing/getStatement" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "statementId": "<statementId>"
}'

iam.api.billing.getStatement(
  credential: CredentialInput,
  input: { tenantId: string; statementId: string },
): Promise<{
  total: number;
  overdue: boolean;
  verified: boolean;
  number: string;
  status: InvoiceStatus;
  issuedAt: number;
  dueAt: number;
  hash: string;
  payments?: InvoicePayment[];
  amountPaidMicros?: number;
  creditNotesMicros?: number;
  invoiceItemIds?: string[];
  advanceBilled?: { subscriptionId: string; period: string }[];
  carryForward?: { creditId: string; amountMicros: number };
  reminders?: { days: number; at: number; recipients: number }[];
  paidAt?: number;
  paidBy?: string;
  paymentReference?: string;
  voidedAt?: number;
  voidedBy?: string;
  voidReason?: string;
  markedUncollectibleAt?: number;
  id: string;
  tenantId: string;
  uniqueKey?: string;
  period: string;
  currency: string;
  periodStart: number;
  periodEnd: number;
  lines: StatementLine[];
  billingReason?: 'period' | 'subscription' | 'manual';
  subtotalMicros: number;
  coupons?: { discountId: string; code: string; name: string; amountMicros: number }[];
  discount?: { percent: number; amountMicros: number };
  commitment?: { minimumMicros: number; trueUpMicros: number };
  creditsMicros: number;
  creditsApplied: { creditId: string; amountMicros: number }[];
  tax?: { label: string; ratePercent: number; amountMicros: number };
  totalMicros: number;
  breakdown: {
    tenants: StatementAllocation[];
    teams: StatementAllocation[];
    departments: (StatementAllocation & { costCenter?: string })[];
    identities: StatementAllocation[];
  };
  billTo: {
    name: string;
    companyName?: string;
    taxId?: string;
    address?: string;
    purchaseOrder?: string;
    costCenter?: string;
    emails: string[];
  };
}>

getTerms

Returns the contract terms of the tenant's billing account: discount, minimum monthly commitment and tax.

• Permission: iam:billing:read on iam/billing/terms.
• Audited as: iam:billing:read.

When an ancestor pays for the tenant the result only says inherited: true; without terms it lists none.

curl -X POST "$IAM_URL/api/iam/billing/getTerms" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.billing.getTerms(
  credential: CredentialInput,
  input: { tenantId: string },
): Promise<TermsView>

grantCredit

Grants credit to a billing account, which its statements draw on, earliest expiry first.

• Permission: Root administrators only (iam:billing:manage on iam/billing/credits).
• Audited as: billing:credit-grant.
• Errors: INVALID_INPUT when the tenant is not a billing account (an organization or a tenant with a profile), for an amount of 0, or an expiresAt in the past.

await iam.api.billing.grantCredit(root, { tenantId: acmeId, amount: 100, reason: 'Launch promotion' });

curl -X POST "$IAM_URL/api/iam/billing/grantCredit" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "amount": 1,
  "reason": "<reason>"
}'

iam.api.billing.grantCredit(
  credential: CredentialInput,
  input: { tenantId: string; amount: number; reason: string; expiresAt?: number },
): Promise<CreditView>

listBudgets

Lists the tenant's budgets with their spend, projection and the thresholds reached in the current window.

• Permission: iam:billing:read on iam/billing/budgets.
• Audited as: iam:billing:read.

curl -X POST "$IAM_URL/api/iam/billing/listBudgets" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.billing.listBudgets(
  credential: CredentialInput,
  input: { tenantId: string },
): Promise<BillingBudgetView[]>

listCoupons

Lists the platform's coupons, newest first, with their redemptions.

• Permission: Root administrators only (iam:billing:read on iam/billing/coupons), called on the root tenant.
• Audited as: iam:billing:read.

active is false for deactivated coupons, those past redeemBy, and those out of redemptions.

curl -X POST "$IAM_URL/api/iam/billing/listCoupons" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.billing.listCoupons(
  credential: CredentialInput,
  input: { tenantId: string },
): Promise<CouponView[]>