> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing in Fees Engine

> New Billing Packages and Billing Calculation in Fees Engine, with new endpoints, 19 new error codes, and OpenAPI v3.1.0 covering volume and maintenance billing.

<Badge stroke icon="calendar-days" iconType="regular">April 14, 2026</Badge> <Badge stroke icon="file-code" iconType="regular">Documentation update</Badge> <Badge color="purple" size="lg" stroke icon="eye" iconType="regular">Review recommended</Badge>

## 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**](/en/reference/midaz/plugins/fees-engine/create-billing-package) — full CRUD endpoints for creating, listing, retrieving, updating, and deleting billing packages
* New [**Billing Calculation endpoint**](/en/reference/midaz/plugins/fees-engine/calculate-billing) — POST /v1/billing/calculate computes charges for a given ledger and period
* New [**Billing Package Examples**](/en/midaz/plugins/fees-engine/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**](/en/midaz/plugins/fees-engine/fees-engine-overview) with billing package concepts, period format (ISO 8601 YYYY-MM and YYYY-Www), and validation rules
* Updated [**Fee Calculation**](/en/midaz/plugins/fees-engine/fee-engine-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**](/en/midaz/plugins/fees-engine/using-fee-engine) with billing package configuration workflow
* Updated [**Best Practices**](/en/midaz/plugins/fees-engine/fees-engine-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**](/en/reference/midaz/plugins/fees-engine/fee-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:

* POST /v1/billing-packages — [Create a billing package](/en/reference/midaz/plugins/fees-engine/create-billing-package)
* GET /v1/billing-packages — [List billing packages](/en/reference/midaz/plugins/fees-engine/list-billing-packages)
* GET /v1/billing-packages/{id} — [Retrieve a billing package](/en/reference/midaz/plugins/fees-engine/retrieve-billing-package)
* PATCH /v1/billing-packages/{id} — [Update a billing package](/en/reference/midaz/plugins/fees-engine/update-billing-package)
* DELETE /v1/billing-packages/{id} — [Delete a billing package](/en/reference/midaz/plugins/fees-engine/delete-billing-package)
* POST /v1/billing/calculate — [Calculate billing for a ledger and period](/en/reference/midaz/plugins/fees-engine/calculate-billing)

New schemas: CreateBillingPackageRequest, UpdateBillingPackageRequest, BillingPackageResponse, CalculateBillingRequest, CalculateBillingResponse.

## Impact

***

This is a documentation update. Existing integrations do not need a migration from this release note alone.

## What you need to do

***

<Steps>
  <Step>
    Review Billing Packages and Billing Calculation documentation before configuring recurring billing models.
  </Step>
</Steps>

### Deadline

None.

### Why

The documentation now covers Fees Engine billing capabilities, examples, and expanded error codes.