April 14, 2026 Documentation update Review recommendedDocumentation Index
Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
Use this file to discover all available pages before exploring further.
Affects
Teams using Fees Engine billing packages or billing calculation. This update applies to the public documentation portal. It does not change the runtime API behavior unless the linked product documentation says otherwise.
What changed
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)
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:
- POST /v1/billing-packages — Create a billing package
- GET /v1/billing-packages — List billing packages
- GET /v1/billing-packages/ — Retrieve a billing package
- PATCH /v1/billing-packages/ — Update a billing package
- DELETE /v1/billing-packages/ — Delete a billing package
- POST /v1/billing/calculate — Calculate billing for a ledger and period
Impact
This is a documentation update. Existing integrations do not need a migration from this release note alone.