Billing & subscriptions¶

Invora Billing manages the commercial relationship with your customers: plans and pricing, subscriptions, metered usage, automated invoicing, prepaid wallets, payment collection, and revenue analytics. Everything lives under /api/billing/v2.

How billing works¶

You define plans — fixed fees, usage-based charges, and feature entitlements.
Your customers subscribe to a plan (via API or self-service portal).
Usage events are metered as customers use your product (documents frozen, submissions made, …).
Invoices are generated automatically at the end of each billing period.
Payments are collected through an integrated payment provider.

flowchart LR
  P[Define plan + metrics] --> S[Subscribe customer]
  S --> U[Meter usage events]
  U --> I[Auto-generate invoice]
  I --> C[Collect payment]
  C --> W[Webhook events]

Base URLs & auth¶

Environment	Base URL
Production	`https://gateway.invora.app`
Staging	`https://stg-gateway.invora.app`

Every call carries a bearer token. Obtain one with the client-credentials grant and export it as $TOKEN:

TOKEN=$(curl -s -X POST https://auth.invora.app/oauth/v2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET" \
  --data-urlencode "scope=openid urn:zitadel:iam:org:project:id:372376660185448530:aud urn:zitadel:iam:user:resourceowner" \
  | jq -r '.access_token')

Bodies are camelCase JSON; monetary fields are exact decimals — see gRPC & JSON transcoding.

Key concepts¶

Concept	What it does
Customer	A billable entity (company, team, or individual) with an `externalId` you control, plus address, currency, tax info, and payment method.
Plan	What a customer pays — base fee, billing interval, usage-based charges, fixed charges, trial period, entitlements.
Subscription	The active billing relationship between a customer and a plan. Can override plan defaults per customer.
Billable metric	A measurable quantity (documents frozen, API calls, seats) with an aggregation rule (sum, count, max, unique, weighted).
Add-on	A one-time charge added to a customer's next invoice.
Coupon	A fixed or percentage discount applied to invoices.
Wallet	A prepaid credit balance that offsets usage charges before payment collection.
Entitlement / feature	A capability gate granted by a plan and queried per subscription.
Alert	A threshold notification on usage or wallet balance.
Payment provider	A connected gateway (Stripe, Adyen, GoCardless, Tap, Moneyhash, Flutterwave, Cashfree).

Define a plan¶

Create a plan with a base fee plus a usage-based charge tied to a billable metric:

curl -X POST https://gateway.invora.app/api/billing/v2/plans \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "business_pro",
    "name": "Business Pro",
    "amountCents": 50000,
    "amountCurrency": "CURRENCY_ENUM_SAR",
    "interval": "PLAN_INTERVAL_MONTHLY",
    "payInAdvance": true,
    "charges": [
      {
        "billableMetricId": "bm_frozen_docs",
        "chargeModel": "CHARGE_MODEL_STANDARD",
        "properties": { "amount": "0.50" }
      }
    ]
  }'

Response

{
  "plan": {
    "id": "01963f80-70a2-7000-8e80-3e062c5c22b3",
    "code": "business_pro",
    "name": "Business Pro",
    "interval": "PLAN_INTERVAL_MONTHLY"
  }
}

curl -X POST https://gateway.invora.app/api/billing/v2/subscriptions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "01963f90-81b3-7000-8f92-4f184e7e44b5",
    "planId": "01963f80-70a2-7000-8e80-3e062c5c22b3",
    "billingTime": "BILLING_TIME_CALENDAR"
  }'

Subscriptions can be upgraded/downgraded mid-cycle with prorated charges, terminated (with an optional final invoice or credit note), and overridden per customer without creating a new plan.

Meter usage¶

Send an event whenever a billable action occurs. transactionId is the idempotency key — resubmitting the same value is a no-op.

curl -X POST https://gateway.invora.app/api/billing/v2/events \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "unique-idempotency-key",
    "externalSubscriptionId": "sub_xyz",
    "code": "frozen_document",
    "timestamp": "2026-04-27T12:00:00Z",
    "properties": { "documentType": "invoice", "regulationId": "zatca" }
  }'

Response

{
  "event": { "transactionId": "unique-idempotency-key", "code": "frozen_document" }
}

Events are aggregated per billing period and priced by the plan's charge model (standard, graduated, package, percentage, or volume). For high volume, batch them via POST /api/billing/v2/events/batch-create:

curl -X POST https://gateway.invora.app/api/billing/v2/events/batch-create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "transactionId": "batch-key-001",
        "externalSubscriptionId": "sub_xyz",
        "code": "frozen_document",
        "timestamp": "2026-04-27T12:00:00Z",
        "properties": { "documentType": "invoice" }
      },
      {
        "transactionId": "batch-key-002",
        "externalSubscriptionId": "sub_xyz",
        "code": "frozen_document",
        "timestamp": "2026-04-27T13:00:00Z",
        "properties": { "documentType": "credit_note" }
      }
    ]
  }'

Response

{ "events": [{ "transactionId": "batch-key-001" }, { "transactionId": "batch-key-002" }] }

Prepaid wallets¶

Offer prepaid credit that automatically offsets usage charges before the payment provider is billed:

curl -X POST https://gateway.invora.app/api/billing/v2/wallets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "01963f90-81b3-7000-8f92-4f184e7e44b5",
    "currency": "CURRENCY_ENUM_SAR",
    "paidCredits": "100.00",
    "grantedCredits": "10.00",
    "rateAmount": "1.0"
  }'

Feature entitlements¶

Gate product features through plans. Define a feature, attach it to a plan, then grant or query it per subscription:

curl -X POST https://gateway.invora.app/api/billing/v2/plans/features \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "code": "regulations_access", "name": "Tax Regulation Compliance" }'

Query at runtime whether a subscription grants a capability (e.g. ZATCA onboarding, connected-business creation) via the subscription entitlement RPCs. The connected-business capability gate in Identity & registration is one of these entitlements.

Analytics¶

Each analytics endpoint is a POST with an optional filter (currency, billing entity, customer, month range):

Metric	Path
Monthly Recurring Revenue	`POST /api/billing/v2/observability/analytics/mrrs`
Gross Revenue	`POST /api/billing/v2/observability/analytics/gross-revenues`
Invoice Collections	`POST /api/billing/v2/observability/analytics/invoice-collections`
Invoiced Usage	`POST /api/billing/v2/observability/analytics/invoiced-usages`
Overdue Balances	`POST /api/billing/v2/observability/analytics/overdue-balances`

curl -X POST https://gateway.invora.app/api/billing/v2/observability/analytics/mrrs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "currency": "CURRENCY_ENUM_SAR" }'

Payment providers¶

Invora Billing integrates with multiple gateways; configure one or more per customer or organization-wide:

Provider	Typical use
Stripe	Cards, bank transfers, 3D Secure
Adyen	Cards, local payment methods
GoCardless	Direct debit (SEPA, BACS, ACH)
Tap	Cards, Apple Pay (MENA)
Moneyhash	MENA payment orchestration
Flutterwave	Cards, mobile money (Africa)
Cashfree	Cards, UPI, netbanking (India)

For a step-by-step guide to connecting Tap and collecting payments from customers, see Collecting payments with Tap.

Customer self-service¶

Generate hosted URLs for customer-facing flows:

Checkout URL — GET /api/billing/v2/customers/{id}/checkout-url (payment-method setup).
Customer portal URL — GET /api/billing/v2/customers/{id}/portal-url (view invoices, manage payment methods and subscriptions).

# Checkout URL — let the customer add or update their payment method
curl -X GET https://gateway.invora.app/api/billing/v2/customers/01963f90-81b3-7000-8f92-4f184e7e44b5/checkout-url \
  -H "Authorization: Bearer $TOKEN"

Response

{ "checkoutUrl": "https://pay.invora.app/checkout/tok_..." }

# Customer portal URL — self-service billing dashboard
curl -X GET https://gateway.invora.app/api/billing/v2/customers/01963f90-81b3-7000-8f92-4f184e7e44b5/portal-url \
  -H "Authorization: Bearer $TOKEN"

Response

{ "portalUrl": "https://pay.invora.app/portal/tok_..." }

A read-only account surface (/api/billing/v2/account/...) lets your end-users view their own subscription, usage, invoices, and wallet — ideal for a self-service billing dashboard.

Platform billing (connected businesses)¶

If you operate a platform with connected businesses, usage from all of them rolls up to your platform's subscription — one bill for the parent. See Multi-tenancy for the tenant model and billing rollup.

RPC reference¶

Every billing service is available over gRPC and REST/JSON under /api/billing/v2. The tables below summarize the operations per service; the API reference carries the per-field request/response schemas.

PlanService & catalog¶

Operation	RPC
Create / update / list / delete a plan	`PlanService.Create` / `Update` / `List` / `Delete`
Define / manage features	`PlanService.CreateFeature` / `UpdateFeature` / `DeleteFeature` / `ListFeatures`
Define a usage metric	`BillableMetricService.Create` / `Update` / `List` / `Delete`
Define a one-time add-on	`AddOnService.Create` / `Update` / `Delete`

CustomerService¶

Operation	RPC
Register / update / get / list / delete	`CustomerService.Create` / `Update` / `Get` / `List` / `Delete`
Current & projected usage	`CustomerService.GetUsage` / `GetProjectedUsage`
Hosted URLs	`CustomerService.GetCheckoutUrl` / `GetCustomerPortalUrl`
Invoice grace period	`CustomerService.UpdateCustomerInvoiceGracePeriod`

SubscriptionService¶

Operation	RPC
Start / get / list / modify	`SubscriptionService.Create` / `Get` / `List` / `Update`
Terminate	`SubscriptionService.Terminate`
Override charges	`SubscriptionService.UpdateSubscriptionCharge` / `UpdateSubscriptionFixedCharge`
Charge filters	`SubscriptionService.CreateChargeFilter` / `DeleteSubscriptionChargeFilter`
Entitlements	`SubscriptionService.CreateOrUpdateEntitlement` / `GetEntitlement` / `ListEntitlements` / `RemoveEntitlement`

InvoiceService¶

Operation	RPC
Create one-off / get / list	`InvoiceService.Create` / `Get` / `List` / `CustomerInvoices`
Finalize	`InvoiceService.Finalize` / `FinalizeAllInvoices`
Refresh / update	`InvoiceService.RefreshInvoice` / `Update`
Download	`InvoiceService.DownloadInvoice` / `DownloadInvoiceXml`
Email	`InvoiceService.ResendInvoiceEmail`
Void / regenerate	`InvoiceService.VoidInvoice` / `RegenerateFromVoided`
Retry	`InvoiceService.RetryInvoice` / `RetryInvoicePayment` / `RetryAllInvoices`
Export	`InvoiceService.CreateDataExport`

WalletService¶

Operation	RPC
Create / update / terminate	`WalletService.CreateCustomerWallet` / `UpdateCustomerWallet` / `TerminateCustomerWallet`
Top up	`WalletService.CreateCustomerWalletTransaction`
Get / list	`WalletService.Get` / `List`
Transactions	`WalletService.ListTransactions` / `GetTransaction` / `ListTransactionConsumptions` / `ListTransactionFundings`

CreditNoteService¶

Operation	RPC
Estimate / create / get / list	`CreditNoteService.GetEstimate` / `Create` / `Get` / `List`
Update / void	`CreditNoteService.Update` / `VoidCreditNote`
Download	`CreditNoteService.DownloadCreditNote` / `DownloadXmlCreditNote`

CouponService¶

Operation	RPC
Create / update / delete	`CouponService.Create` / `Update` / `Delete`
Apply / terminate per customer	`CouponService.CreateAppliedCoupon` / `TerminateAppliedCoupon`
List applied	`CouponService.AppliedCoupons`

Payments¶

Operation	RPC
Connect a provider	`PaymentProviderService.Create{Stripe,Adyen,Gocardless,Tap,Moneyhash,Flutterwave,Cashfree}PaymentProvider`
Record / get / list a payment	`PaymentService.Create` / `Get` / `List`
Payment URL	`PaymentService.GetPaymentUrl`
Payment requests & methods	`PaymentRequestService.Create` / `List` / `PaymentMethods` / `SetPaymentMethodAsDefault`

AlertService¶

Operation	RPC
Create usage / wallet alert	`AlertService.CreateSubscriptionAlert` / `CreateCustomerWalletAlert`
Update / delete / query	`AlertService.UpdateAlert` / `DeleteAlert` / `SubscriptionAlerts` / `WalletAlerts`

ObservabilityService¶

The five analytics RPCs (Mrrs, GrossRevenues, InvoiceCollections, InvoicedUsages, OverdueBalances) plus activity and API logs. All analytics accept an optional currency / entity / customer / month-range filter.

Webhooks¶

Operation	RPC
Register / update / list / delete endpoint	`WebhookEndpointsService.Create` / `Update` / `List` / `Delete`
Browse / inspect deliveries	`WebhookEndpointsService.ListWebhooks` / `GetWebhook` — note `RetryWebhook` does not re-deliver; it returns the stored record (see the webhooks guide, tracked in `invora-backend#228`)

See the dedicated Webhooks guide for payload structure, signature verification, and delivery guarantees.

Identity & registration — plans, subscriptions, and the capability gate at onboarding.
Multi-tenancy — platform billing across connected businesses.
Webhooks — billing event delivery, HMAC, retries.
gRPC & JSON transcoding — decimals, enums, camelCase.
List & filtering — list filter/sort/pagination conventions.
Error handling — status codes and error details.

Billing & subscriptions¶

How billing works¶

Base URLs & auth¶

Key concepts¶

Define a plan¶

Subscribe a customer¶

Meter usage¶

Prepaid wallets¶

Feature entitlements¶

Analytics¶

Payment providers¶

Customer self-service¶

Platform billing (connected businesses)¶

RPC reference¶

PlanService & catalog¶

CustomerService¶

SubscriptionService¶

InvoiceService¶

WalletService¶

CreditNoteService¶

CouponService¶

Payments¶

AlertService¶

ObservabilityService¶

Webhooks¶

Related¶