API reference

GraphQL API

Generated from the repository's canonical SDL artifact (schema/billing_core.graphql), which is regenerated from the running schema and diff-tested in CI — this page cannot drift from the code. The endpoint is POST /api/graphql with a Bearer API token; every team-scoped field takes an explicit teamId and is authorized against the caller's membership scope. Mutations return typed result unions — validation problems are data, not HTTP errors.

Queries

apiVersion: String!

Schema/contract version marker for compatibility checks.

auditExport(…): AuditExport

Audit package for an invoice chain: canonical evidence files + checksum manifest (BC-US-114).

teamId ID!
invoiceIntentId ID!

organization(…): Organization

A single organization the caller belongs to.

organizationId ID!

team(…): Team

A team the caller is a member of.

teamId ID!

teams(…): [Team!]!

Active teams of an organization the caller belongs to.

organizationId ID!

viewer: Viewer

The authenticated principal and its memberships.

Mutations

Object types

AuditExport object

An audit package for one invoice chain with its checksum manifest.

invoiceChainId ID!
intentCount Int!
generatedAt String!
manifestJson String! Canonical JSON manifest listing per-file SHA-256 checksums.
files [AuditExportFile!]!

BookInvoiceAccepted object

operation Operation! Durable booking operation to follow.
clientMutationId String!

CreditClose object

One monthly customer-credit close (§11.5 lifecycle).

id ID!
currency String!
periodStart Date!
periodEndExclusive Date!
transactionCutoff DateTime!
closeKind String! regular, reversal, or replacement (ADR-031 compensating closes).
reversalOfCloseId ID For a correction close: the close it corrects.
corrections [CreditClose!]! Correction closes referencing this close, oldest first.
state String! Current §11.5 state (open, ready, approved, posting, reconciled, closed, ...).
openingMinor MoneyMinorUnits
closingMinor MoneyMinorUnits
netChangeMinor MoneyMinorUnits
economicLiabilityLineMinor MoneyMinorUnits
ledgerTransactionCount Int
reportSha256 String
closedAt DateTime
movements [CreditCloseMovement!]!
evidence [CreditCloseEvidenceMeta!]!
externalVoucherNumber String Voucher number of the posted aggregate document, once posted.
report CreditCloseReport One stored immutable evidence file with its exact bytes.

CreditClosePolicy object

An accountant-approved posting policy version for monthly closes.

id ID!
version Int!
effectiveFrom Date!
journalNumber Int!
liabilityAccountNumber Int!
postingMode String!
defaultOffsetAccountNumber Int
postZeroDelta Boolean!
vatNeutral Boolean!
settlementMode String! SPEC §9.4.1: none, erp_customer_settlement, or external_reference.
settlementClearingAccountNumber Int
settlementContraAccountNumber Int

CreditDispositionPolicy object

A versioned remaining-credit disposition policy (BC-US-109).

version Int!
policy String! retain, refund, or expire_after.
expireAfterDays Int
effectiveFrom DateTime!

IdempotencyConflict object

The idempotency key was reused with materially different input.

code String!
message String!
clientMutationId String

RequestCreditCloseReversalSuccess object

reversalClose CreditClose! The frozen reversal close carrying the mirrored bridge.
clientMutationId String!

SupersedeInvoiceIntentSuccess object

invoiceIntent InvoiceIntent! The replacement intent (intentVersion incremented, same chain).
clientMutationId String!

SynchronizeInvoiceAccepted object

operation Operation! Durable operation to follow; work continues asynchronously.
clientMutationId String!

UsageEventConflict object

The external event ID was already used with a different payload (BC-US-050).

code String!
message String!
clientMutationId String

UsageIngestOutcome object

Result of one ingested usage event.

status String! accepted | duplicate | quarantined
usageEventId ID
quarantineReason String

VoidUsageEventSuccess object

status String! voided | already_voided
clientMutationId String!

Result unions

Input types

AddTeamMemberInput input

teamId ID!
userId ID! An existing user with an active membership in the owning organization.
teamRoles [String!]! team_admin, billing_admin, finance_operator, auditor, integration_client.
clientMutationId String!

ArchiveTeamInput input

organizationId ID!
targetTeamId ID! The team to archive. Named so the scope stays organization-level: an owner/admin need not be a member of the team being archived.
clientMutationId String!

ChangeOrganizationRolesInput input

organizationId ID!
membershipId ID!
organizationRoles [String!]! organization_owner, organization_admin, or organization_member.
clientMutationId String!

ChangeTeamRolesInput input

teamId ID!
membershipId ID!
teamRoles [String!]! team_admin, billing_admin, finance_operator, auditor, integration_client.
clientMutationId String!

CreateCreditClosePolicyInput input

teamId ID!
effectiveFrom Date!
journalNumber Int!
liabilityAccountNumber Int!
defaultOffsetAccountNumber Int!
postZeroDelta Boolean
vatNeutral Boolean
settlementMode String none (default — blocks automatic credit application), erp_customer_settlement, or external_reference.
settlementClearingAccountNumber Int
settlementContraAccountNumber Int
clientMutationId String!

FixedRecurringPricingInput input

unitPrice Decimal! Unit price per interval in major currency units.

FreezeInvoiceIntentInput input

teamId ID!
subscriptionId ID!
asOf Date! The preview date; the billing period containing it is frozen.
billingRunId ID
idempotencyKey String!
clientMutationId String!

GenerateCreditCloseInput input

teamId ID!
currency String!
periodDate Date! Any date inside the close month; the calendar month is frozen.
bootstrapOpeningMinor MoneyMinorUnits Required only for the very first close of a currency (zero is valid).
policyVersionId ID Defaults to the latest policy version.
idempotencyKey String!
clientMutationId String!

GenerateCreditCloseReplacementInput input

teamId ID!
creditCloseId ID! The reversed close whose period is being reposted.
policyVersionId ID! The corrected posting-policy version.
reason String! Recorded correction reason — required for the audit trail.
clientMutationId String!

InviteOrganizationMemberInput input

organizationId ID!
email String!
organizationRoles [String!] organization_owner, organization_admin, or organization_member.
teamId ID
teamRoles [String!] team_admin, billing_admin, finance_operator, auditor, integration_client.
clientMutationId String!

PackagePricingInput input

packageSize Decimal!
packagePrice Decimal! Price per whole package in major currency units.

RecordExternalSettlementInput input

teamId ID!
settlementId ID!
externalReference String! The authoritative external receivables system's settlement reference.
clientMutationId String!

RequestCreditCloseReversalInput input

teamId ID!
creditCloseId ID!
reason String! Recorded correction reason — required for the audit trail.
clientMutationId String!

RevokeOrganizationInvitationInput input

organizationId ID!
invitationId ID!
clientMutationId String!

SetCreditDispositionPolicyInput input

teamId ID!
creditAccountId ID!
policy String! retain, refund, or expire_after.
expireAfterDays Int Required for expire_after.
clientMutationId String!

StandardMeteredPricingInput input

unitRate Decimal! Per-unit rate in major currency units.

VoidUsageEventInput input

teamId ID!
externalEventId String! The measurement to void.
voidEventId String! External ID of the void itself (idempotency).
replacement UsageBatchEventInput Optional corrected measurement submitted with the void (BC-US-052).
clientMutationId String!

Enums

BillingTiming enum

IN_ADVANCE
IN_ARREARS

CancellationMode enum

IMMEDIATE
END_OF_PERIOD

IntervalUnit enum

MONTH
DAY

RecognitionMode enum

POINT_IN_TIME
OVER_TIME

Scalars

Boolean scalar

The `Boolean` scalar type represents `true` or `false`.

Date scalar

ISO 8601 calendar date, e.g. `2026-09-15`.

DateTime scalar

ISO 8601 UTC timestamp, e.g. `2026-08-21T15:00:00Z`.

Decimal scalar

Arbitrary-precision decimal serialized as a string, e.g. `"12.5"`. Floats are rejected to protect precision.

ID scalar

The `ID` scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `"4"`) or integer (such as `4`) input value will be accepted as an ID.

Int scalar

The `Int` scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Json scalar

A JSON object (string keys, JSON-safe values). Used only where a stable typed structure is not yet known (SPEC §14.8 discourages generic blobs; usage-event properties are schema-allowlisted downstream).

MoneyMinorUnits scalar

Integer currency amount in minor units (e.g. øre/cents). Currency travels in a sibling field. JSON floats are rejected.

String scalar

The `String` scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.