Skip to content

Billing & Subscriptions

Invora Billing handles the commercial relationship with your customers: plans, pricing, subscriptions, metered usage, automated invoicing, and payment collection.

How Billing Works

  1. You define plans with fixed fees, usage-based charges, and feature entitlements
  2. Your customers subscribe to a plan (via API or self-service portal)
  3. Usage events are tracked as customers use your product (documents frozen, submissions made, etc.)
  4. Invoices are generated automatically at the end of each billing period
  5. Payments are collected via integrated payment providers (Stripe, Adyen, GoCardless, Tap, etc.)

Key Concepts

Concept What It Does
Plan Defines what a customer pays — base fee, per-unit charges, tiers, trial period
Subscription An active billing relationship between a customer and a plan
Billable Metric Tracks usage events (e.g., documents frozen, API calls, active users)
Add-on One-time charge added to a customer's next invoice
Coupon Percentage or fixed discount applied to invoices
Wallet Prepaid credit balance that offsets usage charges
Entitlement Feature access granted by a plan (e.g., "regulations" capability, "connected businesses")
Alert Notification when usage or wallet balance crosses a threshold

Managing Plans

Create a plan with fixed and usage-based charges:

POST /api/billing/v2/plans
{
  "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"}
    }
  ]
}

Subscribing Customers

POST /api/billing/v2/subscriptions
{
  "customerId": "cust_abc",
  "planId": "plan_business_pro",
  "billingTime": "BILLING_TIME_CALENDAR"
}

Subscriptions can be: - Upgraded/downgraded — change plan mid-cycle with prorated charges - Terminated — end the subscription with optional credit note or final invoice - Overridden — customize specific charges for individual customers without creating a new plan

Tracking Usage

Send events whenever a billable action occurs:

POST /api/billing/v2/events
{
  "transactionId": "unique-idempotency-key",
  "externalSubscriptionId": "sub_xyz",
  "code": "frozen_document",
  "timestamp": "2026-04-27T12:00:00Z",
  "properties": {
    "documentType": "invoice",
    "regulationId": "zatca"
  }
}

Events are aggregated per billing period and priced according to the plan's charge model (per-unit, graduated, package, percentage, or volume).

Automated Invoicing

At the end of each billing period, Invora automatically: 1. Calculates recurring + usage charges 2. Applies coupons and wallet credits 3. Generates a billing invoice 4. Converts it to a UBL document in the invoicing system 5. Sends it to the customer's payment provider 6. Triggers webhook events for your application

Payment Providers

Invora integrates with multiple payment gateways:

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

Configure providers per-customer or organization-wide.

Prepaid Wallets

Offer prepaid credit to your customers:

POST /api/billing/v2/wallets
{
  "customerId": "cust_abc",
  "currency": "CURRENCY_ENUM_SAR",
  "paidCredits": "100.00",
  "grantedCredits": "10.00",
  "rateAmount": "1.0"
}

Wallet credits automatically offset usage charges before payment provider is billed.

Feature Entitlements

Control feature access through plans. First define a feature in your catalog:

POST /api/billing/v2/plans/features
{
  "code": "regulations_access",
  "name": "Tax Regulation Compliance"
}

Attach features to plans, then grant or query them per subscription via the subscription entitlements endpoints (/api/billing/v2/subscriptions/{subscriptionId}/entitlements). Check at runtime whether a customer's subscription grants a specific capability (e.g., ZATCA onboarding, connected business creation).

Analytics

Track key business metrics. Each analytics endpoint accepts a POST with an optional filter (currency, billing entity, customer, month range):

  • Monthly Recurring Revenue (MRR) — 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

Customer Self-Service

Generate checkout and portal URLs for customer-facing experiences:

  • Checkout URL — redirect customers to complete payment setup
  • Customer Portal URL — let customers view invoices, update payment methods, and manage subscriptions

Platform Billing (Connected Businesses)

If you operate a platform with connected businesses (resellers, franchises, multi-entity):

  • Your platform subscribes to a plan (e.g., "Platform Pro — 50 connected businesses")
  • Connected businesses create documents and use features under your subscription
  • Usage from all connected businesses rolls up to your platform's billing
  • View per-business costs via GET /api/admin/invoices/v2/tenants/{tenantId}/usage-stats

See Multi-Tenancy for details on managing connected businesses.