Skip to main content
April 14th, 2026 Updated This update introduces comprehensive documentation for two new Fees Engine capabilities: Billing Packages and Billing Calculation. These features allow you to configure recurring billing models — volume-based and maintenance-based — and calculate charges automatically based on ledger activity.

​
Billing Packages: volume and maintenance billing

Billing Packages let you define how your platform charges clients for usage. The Fees Engine now supports two billing types:
  • Volume billing — charges based on transaction count within a period, with support for tiered pricing, free quotas, and discount tiers
  • Maintenance billing — charges based on the number of active accounts in a segment or portfolio

​
What’s new

  • New Billing Packages API reference — full CRUD endpoints for creating, listing, retrieving, updating, and deleting billing packages
  • New Billing Calculation endpoint — POST /v1/billing/calculate computes charges for a given ledger and period
  • New Billing Package Examples page with four real-world scenarios: tiered boleto pricing, Pix volume billing with discount tiers, account maintenance billing, and combined volume + maintenance billing
  • Updated Fees Engine Overview with billing package concepts, period format (ISO 8601 YYYY-MM and YYYY-Www), and validation rules
  • Updated Fee Calculation guide with billing calculation flow: freeQuota → tiers → discountTiers, countMode semantics (perRoute vs perAccount), all-or-nothing behavior, and audit metadata
  • Updated Using Fees Engine with billing package configuration workflow
  • Updated Best Practices with billing-specific guidance on period selection, segment-based exemptions, and discount tier strategy

​
Why it matters

If you’re building a platform that needs to charge clients based on transaction volume or active accounts, Billing Packages give you a declarative way to define pricing models — including tiered pricing with automatic discount application. The calculation endpoint returns a ready-to-execute transactionPayload that you can post directly to the Ledger, keeping billing fully integrated with your financial records.

​
Updated error catalog

The Fees Engine Error List has been expanded with 19 new error codes (FEE-0052 through FEE-0070) covering billing-specific validations:
  • Missing or invalid billing package fields (period, type, pricingModel, feeAmount, assetCode)
  • Tier configuration errors (overlapping tiers, missing thresholds, invalid discount percentages)
  • Calculation failures (segment resolution, service dependencies)
  • Account target validation (segmentId, portfolioId, or aliases — exactly one required)
The total error catalog now covers 69 error codes across all Fees Engine operations.

​
OpenAPI spec updated to v3.1.0

The Fees Engine OpenAPI specification has been bumped from v3.0.0 to v3.1.0, reflecting all new endpoints and schemas: New schemas: CreateBillingPackageRequest, UpdateBillingPackageRequest, BillingPackageResponse, CalculateBillingRequest, CalculateBillingResponse.