Skip to content

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.

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

OperationTypeScriptGoPython
GetBalanceTransactionsConnectionGetBalanceTransactionsConnectionDocumentGetBalanceTransactionsConnectionget_balance_transactions_connection

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

OperationTypeScriptGoPython
GetBillingDetailsGetBillingDetailsDocumentGetBillingDetailsget_billing_details

The current tenant’s plan lifecycle: a FrameWorks arrangement, a scheduled move to Free and how far a scheduled plan change has progressed.

billingLifecycle: BillingLifecycle

Returns: BillingLifecycle (BillingLifecycle)

SDK

OperationTypeScriptGoPython
GetBillingLifecycleGetBillingLifecycleDocumentGetBillingLifecycleget_billing_lifecycle

Get the current billing status including subscription tier and usage.

billingStatus: BillingStatus

Returns: BillingStatus (BillingStatus)

SDK

OperationTypeScriptGoPython
GetBillingStatusGetBillingStatusDocumentGetBillingStatusget_billing_status

List available billing tiers and their pricing.

billingTiers: [BillingTier!]

Returns: [BillingTier!] (BillingTier)

SDK

OperationTypeScriptGoPython
GetBillingTiersGetBillingTiersDocumentGetBillingTiersget_billing_tiers

Fetch a single invoice by ID.

invoice(
id: ID!
): Invoice

Returns: Invoice (Invoice)

Arguments

  • id: ID! — The invoice ID.

SDK

OperationTypeScriptGoPython
GetInvoiceGetInvoiceDocumentGetInvoiceget_invoice

List invoices for the current tenant.

invoicesConnection(
page: ConnectionInput
): InvoicesConnection!

Returns: InvoicesConnection! (InvoicesConnection)

Arguments

SDK

OperationTypeScriptGoPython
GetInvoicesConnectionGetInvoicesConnectionDocumentGetInvoicesConnectionget_invoices_connection

List Mollie mandates for the current tenant.

mollieMandates: [MollieMandate!]!

Returns: [MollieMandate!]! (MollieMandate)

SDK

OperationTypeScriptGoPython
GetMollieMandatesGetMollieMandatesDocumentGetMollieMandatesget_mollie_mandates

Fetch one invoice payment owned by the current tenant.

payment(
id: ID!
): InvoicePayment

Returns: InvoicePayment (InvoicePayment)

Arguments

  • id: ID!

SDK

OperationTypeScriptGoPython
GetPaymentGetPaymentDocumentGetPaymentget_payment

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

OperationTypeScriptGoPython
GetPaymentsConnectionGetPaymentsConnectionDocumentGetPaymentsConnectionget_payments_connection

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

OperationTypeScriptGoPython
GetPrepaidBalanceGetPrepaidBalanceDocumentGetPrepaidBalanceget_prepaid_balance

Get aggregated usage metrics for the tenant.

tenantUsage(
timeRange: TimeRangeInput
): TenantUsage

Returns: TenantUsage (TenantUsage)

Arguments

SDK

OperationTypeScriptGoPython
GetTenantUsageGetTenantUsageDocumentGetTenantUsageget_tenant_usage

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

OperationTypeScriptGoPython
GetUsageAggregatesGetUsageAggregatesDocumentGetUsageAggregatesget_usage_aggregates

List detailed usage records with pagination.

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

Returns: UsageRecordsConnection! (UsageRecordsConnection)

Arguments

SDK

OperationTypeScriptGoPython
ListUsageRecordsListUsageRecordsDocumentListUsageRecordslist_usage_records

Change the postpaid billing tier. Upgrades start a fresh month and offset the replacement fee with the unused retained paid old fee, capped at the replacement price, without cash refund or spendable balance. Provider or metering reconciliation can leave them pending. Enterprise purchases and moves to a higher tier with a lower base price require an operator arrangement. Downgrades take effect at the end of the current billing period. A Stripe or Mollie subscription is repriced to the lower tier before it renews; a move to Free cancels it instead, at billingLifecycle.freeMoveFinalAt. Choosing the current tier cancels a downgrade while billingLifecycle.pendingTierState is SCHEDULED; it needs no billing profile or collection setup. A refusal returns ValidationError whose code is one of PENDING_CHECKOUT, PENDING_FREE_FALLBACK, PENDING_UPGRADE, OUTSTANDING_GRANT, ACCOUNT_CLOSED, DOWNGRADE_HELD, PAID_TERM_ENDING, PROVIDER_SUBSCRIPTION_LIVE, TIER_NOT_SELF_SERVICE, INVOICES_OUTSTANDING, COLLECTION_SETUP_REQUIRED or BILLING_PROFILE_REQUIRED, with a message to show the customer.

changeBillingTier(
tierId: ID!
): ChangeBillingTierResult!

Returns: ChangeBillingTierResult! (ChangeBillingTierResult)

Arguments

  • tierId: ID! — The target billing tier. Must be active, non-Enterprise and postpaid (tier_level >= 1).

SDK

OperationTypeScriptGoPython
ChangeBillingTierChangeBillingTierDocumentChangeBillingTierchange_billing_tier

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

SDK

OperationTypeScriptGoPython
CreateCardTopupCreateCardTopupDocumentCreateCardTopupcreate_card_topup

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

SDK

OperationTypeScriptGoPython
CreateCryptoTopupCreateCryptoTopupDocumentCreateCryptoTopupcreate_crypto_topup

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. Requires an active, non-Enterprise postpaid tier with tier_level >= 1. Existing native subscriptions use changeBillingTier. A same-tier advance collection switch preserves the paid term. 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

OperationTypeScriptGoPython
CreateMollieFirstPaymentCreateMollieFirstPaymentDocumentCreateMollieFirstPaymentcreate_mollie_first_payment

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

OperationTypeScriptGoPython
CreateMollieSubscriptionCreateMollieSubscriptionDocumentCreateMollieSubscriptioncreate_mollie_subscription

Create a payment for subscription or usage.

createPayment(
input: CreatePaymentInput!
): CreatePaymentResult!

Returns: CreatePaymentResult! (CreatePaymentResult)

Arguments

SDK

OperationTypeScriptGoPython
CreatePaymentCreatePaymentDocumentCreatePaymentcreate_payment

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

OperationTypeScriptGoPython
CreateStripeBillingPortalCreateStripeBillingPortalDocumentCreateStripeBillingPortalcreate_stripe_billing_portal

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 active, non-Enterprise postpaid tier to subscribe to (tier_level >= 1).
  • 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

OperationTypeScriptGoPython
CreateStripeCheckoutCreateStripeCheckoutDocumentCreateStripeCheckoutcreate_stripe_checkout

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

OperationTypeScriptGoPython
CryptoTopupStatusMutationCryptoTopupStatusMutationDocumentCryptoTopupStatusMutationcrypto_topup_status_mutation

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! — Active, non-Enterprise postpaid tier with tier_level >= 1. Already-postpaid tenants on this tier are unchanged, including a tier retired after purchase. An outstanding operator grant or tier upgrade must finish first.

SDK

OperationTypeScriptGoPython
PromoteToPaidPromoteToPaidDocumentPromoteToPaidpromote_to_paid

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

OperationTypeScriptGoPython
SubmitX402PaymentSubmitX402PaymentDocumentSubmitX402Paymentsubmit_x_402_payment

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

updateBillingDetails(
input: UpdateBillingDetailsInput!
): BillingDetails!

Returns: BillingDetails! (BillingDetails)

Arguments

SDK

OperationTypeScriptGoPython
UpdateBillingDetailsUpdateBillingDetailsDocumentUpdateBillingDetailsupdate_billing_details