Billing and usage

GraphQL schema reference · API guide · SDKs

Billing tiers, invoices, payments, top-ups, prepaid balance, and usage records.

Types used by more than one domain are on Shared types.

Queries

Query.balanceTransactionsConnection

List balance transactions for the tenant with pagination.

balanceTransactionsConnection(
  page: ConnectionInput
  transactionType: String
  timeRange: TimeRangeInput
): BalanceTransactionsConnection!

Returns: BalanceTransactionsConnection! (BalanceTransactionsConnection)

Arguments

page: ConnectionInput (ConnectionInput) — Pagination options.
transactionType: String — Filter by transaction type: topup, usage, refund, adjustment.
timeRange: TimeRangeInput (TimeRangeInput) — Time range to query.

SDK

Operation	TypeScript	Go	Python
GetBalanceTransactionsConnection	`GetBalanceTransactionsConnectionDocument`	`GetBalanceTransactionsConnection`	`get_balance_transactions_connection`

Query.billingDetails

Get billing details for the current tenant. Email and address are required before funding or postpaid setup. A VAT/tax identifier is optional customer-supplied data and is not automatically verified.

billingDetails: BillingDetails

Returns: BillingDetails (BillingDetails)

SDK

Operation	TypeScript	Go	Python
GetBillingDetails	`GetBillingDetailsDocument`	`GetBillingDetails`	`get_billing_details`

Query.billingStatus

Get the current billing status including subscription tier and usage.

billingStatus: BillingStatus

Returns: BillingStatus (BillingStatus)

SDK

Operation	TypeScript	Go	Python
GetBillingStatus	`GetBillingStatusDocument`	`GetBillingStatus`	`get_billing_status`

Query.billingTiers

List available billing tiers and their pricing.

billingTiers: [BillingTier!]

Returns: [BillingTier!] (BillingTier)

SDK

Operation	TypeScript	Go	Python
GetBillingTiers	`GetBillingTiersDocument`	`GetBillingTiers`	`get_billing_tiers`

Query.invoice

Fetch a single invoice by ID.

invoice(
  id: ID!
): Invoice

Returns: Invoice (Invoice)

Arguments

id: ID! — The invoice ID.

SDK

Operation	TypeScript	Go	Python
GetInvoice	`GetInvoiceDocument`	`GetInvoice`	`get_invoice`

Query.invoicesConnection

List invoices for the current tenant.

invoicesConnection(
  page: ConnectionInput
): InvoicesConnection!

Returns: InvoicesConnection! (InvoicesConnection)

Arguments

page: ConnectionInput (ConnectionInput) — Pagination options.

SDK

Operation	TypeScript	Go	Python
GetInvoicesConnection	`GetInvoicesConnectionDocument`	`GetInvoicesConnection`	`get_invoices_connection`

Query.mollieMandates

List Mollie mandates for the current tenant.

mollieMandates: [MollieMandate!]!

Returns: [MollieMandate!]! (MollieMandate)

SDK

Operation	TypeScript	Go	Python
GetMollieMandates	`GetMollieMandatesDocument`	`GetMollieMandates`	`get_mollie_mandates`

Query.payment

Fetch one invoice payment owned by the current tenant.

payment(
  id: ID!
): InvoicePayment

Returns: InvoicePayment (InvoicePayment)

Arguments

id: ID!

SDK

Operation	TypeScript	Go	Python
GetPayment	`GetPaymentDocument`	`GetPayment`	`get_payment`

Query.paymentsConnection

List invoice payments owned by the current tenant.

paymentsConnection(
  page: ConnectionInput
  invoiceId: ID
  status: String
  method: String
): InvoicePaymentsConnection!

Returns: InvoicePaymentsConnection! (InvoicePaymentsConnection)

Arguments

page: ConnectionInput (ConnectionInput)
invoiceId: ID
status: String
method: String

SDK

Operation	TypeScript	Go	Python
GetPaymentsConnection	`GetPaymentsConnectionDocument`	`GetPaymentsConnection`	`get_payments_connection`

Query.prepaidBalance

Get the current prepaid balance for the tenant, held in EUR. Only available for tenants with billing_model = ‘prepaid’.

prepaidBalance: PrepaidBalance

Returns: PrepaidBalance (PrepaidBalance)

SDK

Operation	TypeScript	Go	Python
GetPrepaidBalance	`GetPrepaidBalanceDocument`	`GetPrepaidBalance`	`get_prepaid_balance`

Query.tenantUsage

Get aggregated usage metrics for the tenant.

tenantUsage(
  timeRange: TimeRangeInput
): TenantUsage

Returns: TenantUsage (TenantUsage)

Arguments

timeRange: TimeRangeInput (TimeRangeInput) — Time range to query.

SDK

Operation	TypeScript	Go	Python
GetTenantUsage	`GetTenantUsageDocument`	`GetTenantUsage`	`get_tenant_usage`

Query.usageAggregates

Get aggregated usage data grouped by time interval.

usageAggregates(
  timeRange: TimeRangeInput!
  granularity: String = "daily"
  usageTypes: [String!]
): [UsageAggregate!]!

Returns: [UsageAggregate!]! (UsageAggregate)

Arguments

timeRange: TimeRangeInput! (TimeRangeInput) — Time range to query (required).
granularity: String (default "daily") — Aggregation granularity: hourly, daily, or monthly.
usageTypes: [String!] — Filter by usage types.

SDK

Operation	TypeScript	Go	Python
GetUsageAggregates	`GetUsageAggregatesDocument`	`GetUsageAggregates`	`get_usage_aggregates`

Query.usageRecordsConnection

List detailed usage records with pagination.

usageRecordsConnection(
  page: ConnectionInput
  timeRange: TimeRangeInput
): UsageRecordsConnection!

Returns: UsageRecordsConnection! (UsageRecordsConnection)

Arguments

page: ConnectionInput (ConnectionInput) — Pagination options.
timeRange: TimeRangeInput (TimeRangeInput) — Time range to query.

SDK

Operation	TypeScript	Go	Python
ListUsageRecords	`ListUsageRecordsDocument`	`ListUsageRecords`	`list_usage_records`

Mutations

Mutation.changeBillingTier

Change the postpaid billing tier. Upgrades apply immediately and reconcile cluster access; downgrades are scheduled for the current billing period end so the tenant keeps paid entitlements until the period closes.

changeBillingTier(
  tierId: ID!
): ChangeBillingTierResult!

Returns: ChangeBillingTierResult! (ChangeBillingTierResult)

Arguments

tierId: ID! — The target billing tier. Must be an active postpaid tier (tier_level >= 1).

SDK

Operation	TypeScript	Go	Python
ChangeBillingTier	`ChangeBillingTierDocument`	`ChangeBillingTier`	`change_billing_tier`

Mutation.createCardTopup

Create a card checkout session for prepaid balance top-up. Returns a URL to redirect the user to Stripe/Mollie checkout. After successful payment, balance is credited automatically via webhook.

createCardTopup(
  input: CreateCardTopupInput!
): CardTopupResult!

Returns: CardTopupResult! (CardTopupResult)

Arguments

input: CreateCardTopupInput! (CreateCardTopupInput)

SDK

Operation	TypeScript	Go	Python
CreateCardTopup	`CreateCardTopupDocument`	`CreateCardTopup`	`create_card_topup`

Mutation.createCryptoTopup

Create a crypto deposit address for prepaid balance top-up. Returns an HD-derived address for the agent to send crypto. This is the agent-friendly payment method - no human-in-the-loop required.

createCryptoTopup(
  input: CreateCryptoTopupInput!
): CryptoTopupResult!

Returns: CryptoTopupResult! (CryptoTopupResult)

Arguments

input: CreateCryptoTopupInput! (CreateCryptoTopupInput)

SDK

Operation	TypeScript	Go	Python
CreateCryptoTopup	`CreateCryptoTopupDocument`	`CreateCryptoTopup`	`create_crypto_topup`

Mutation.createMollieFirstPayment

Create a Mollie first payment to establish a mandate. For iDEAL: User pays via bank → SEPA Direct Debit mandate is created. For card: User enters card → card mandate is created. After successful payment, call createMollieSubscription to start recurring billing.

createMollieFirstPayment(
  tierId: ID!
  method: String!
  redirectUrl: String!
): MollieFirstPaymentResult!

Returns: MollieFirstPaymentResult! (MollieFirstPaymentResult)

Arguments

tierId: ID! — The billing tier to subscribe to.
method: String! — Payment method: ‘ideal’, ‘creditcard’, ‘bancontact’.
redirectUrl: String! — URL to redirect to after payment.

SDK

Operation	TypeScript	Go	Python
CreateMollieFirstPayment	`CreateMollieFirstPaymentDocument`	`CreateMollieFirstPayment`	`create_mollie_first_payment`

Mutation.createMollieSubscription

Create a Mollie subscription after mandate is valid. Call this after the first payment webhook confirms mandate creation.

createMollieSubscription(
  tierId: ID!
  mandateId: String!
  description: String
): MollieSubscriptionResult!

Returns: MollieSubscriptionResult! (MollieSubscriptionResult)

Arguments

tierId: ID! — The billing tier to subscribe to.
mandateId: String! — The mandate ID from the first payment.
description: String — Optional description for the subscription.

SDK

Operation	TypeScript	Go	Python
CreateMollieSubscription	`CreateMollieSubscriptionDocument`	`CreateMollieSubscription`	`create_mollie_subscription`

Mutation.createPayment

Create a payment for subscription or usage.

createPayment(
  input: CreatePaymentInput!
): CreatePaymentResult!

Returns: CreatePaymentResult! (CreatePaymentResult)

Arguments

input: CreatePaymentInput! (CreatePaymentInput) — Payment details.

SDK

Operation	TypeScript	Go	Python
CreatePayment	`CreatePaymentDocument`	`CreatePayment`	`create_payment`

Mutation.createStripeBillingPortal

Create a Stripe Billing Portal session. Returns a URL to redirect the user to manage their subscription.

createStripeBillingPortal(
  returnUrl: String!
): StripeBillingPortalResult!

Returns: StripeBillingPortalResult! (StripeBillingPortalResult)

Arguments

returnUrl: String! — URL to redirect to when user is done.

SDK

Operation	TypeScript	Go	Python
CreateStripeBillingPortal	`CreateStripeBillingPortalDocument`	`CreateStripeBillingPortal`	`create_stripe_billing_portal`

Mutation.createStripeCheckout

Create a Stripe Checkout Session for subscription setup. Returns a URL to redirect the user to Stripe’s hosted checkout page. After successful payment, user is redirected to successUrl.

createStripeCheckout(
  tierId: ID!
  billingPeriod: String!
  successUrl: String!
  cancelUrl: String!
): StripeCheckoutResult!

Returns: StripeCheckoutResult! (StripeCheckoutResult)

Arguments

tierId: ID! — The billing tier to subscribe to.
billingPeriod: String! — Billing period: ‘monthly’ or ‘yearly’.
successUrl: String! — URL to redirect to after successful checkout.
cancelUrl: String! — URL to redirect to if user cancels.

SDK

Operation	TypeScript	Go	Python
CreateStripeCheckout	`CreateStripeCheckoutDocument`	`CreateStripeCheckout`	`create_stripe_checkout`

Mutation.cryptoTopupStatus

Check the status of a crypto top-up (for polling). Returns current status, confirmations, and credited amount when complete.

cryptoTopupStatus(
  topupId: ID!
): CryptoTopupStatus!

Returns: CryptoTopupStatus! (CryptoTopupStatus)

Arguments

topupId: ID!

SDK

Operation	TypeScript	Go	Python
CryptoTopupStatusMutation	`CryptoTopupStatusMutationDocument`	`CryptoTopupStatusMutation`	`crypto_topup_status_mutation`

Mutation.promoteToPaid

Switch from prepaid to a selected postpaid tier. A verified email is always required. Free needs no billing profile or payment provider; paid tiers require confirmed provider collection. Existing prepaid balance is carried forward as account credit.

promoteToPaid(
  tierId: ID!
): PromoteToPaidResult!

Returns: PromoteToPaidResult! (PromoteToPaidResult)

Arguments

tierId: ID! — The billing tier to subscribe to.

SDK

Operation	TypeScript	Go	Python
PromoteToPaid	`PromoteToPaidDocument`	`PromoteToPaid`	`promote_to_paid`

Mutation.submitX402Payment

Submit an x402 payment payload to settle a 402 response or top up balance. Authenticated members may settle viewer resources; direct top-ups and non-viewer resources require billing management authority on the target tenant.

submitX402Payment(
  payment: String!
  resource: String
): SubmitX402PaymentResult!

Returns: SubmitX402PaymentResult! (SubmitX402PaymentResult)

Arguments

payment: String! — Base64-encoded x402 payment payload.
resource: String — Optional resource being paid for. Viewer resources credit their resolved owner tenant; omission defaults to the authenticated tenant.

SDK

Operation	TypeScript	Go	Python
SubmitX402Payment	`SubmitX402PaymentDocument`	`SubmitX402Payment`	`submit_x_402_payment`

Mutation.updateBillingDetails

Update billing details for the current tenant. Required before any payment for VAT invoicing.

updateBillingDetails(
  input: UpdateBillingDetailsInput!
): BillingDetails!

Returns: BillingDetails! (BillingDetails)

Arguments

input: UpdateBillingDetailsInput! (UpdateBillingDetailsInput)

SDK

Operation	TypeScript	Go	Python
UpdateBillingDetails	`UpdateBillingDetailsDocument`	`UpdateBillingDetails`	`update_billing_details`

Types

Billing and usage types: BalanceTransaction, BalanceTransactionEdge, BalanceTransactionsConnection, BillingAddress, BillingAddressInput, BillingDetails, BillingFeatures, BillingStatus, BillingTier, CardPaymentProvider, CardTopupResult, ChangeBillingTierPayload, ChangeBillingTierResult, CostEntry, CountryMetrics, CreateCardTopupInput, CreateCryptoTopupInput, CreatePaymentInput, CreatePaymentResult, CryptoAsset, CryptoTopupResult, CryptoTopupStatus, Currency, CurrencyConversion, EntitlementEntry, Invoice, InvoiceEdge, InvoicePayment, InvoicePaymentEdge, InvoicePaymentsConnection, InvoiceStatus, InvoicesConnection, LineItem, LiveUsageSummary, MollieFirstPayment, MollieFirstPaymentResult, MollieMandate, MollieSubscription, MollieSubscriptionResult, Money, Payment, PaymentMethod, PaymentStatus, PrepaidBalance, PricingRule, PromoteToPaidPayload, PromoteToPaidResult, StripeBillingPortalResult, StripeBillingPortalSession, StripeCheckoutResult, StripeCheckoutSession, SubmitX402PaymentResult, TenantSubscription, TenantUsage, UpdateBillingDetailsInput, UsageAggregate, UsageEntry, UsageRecord, UsageRecordEdge, UsageRecordsConnection, X402PaymentResult