> ## 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.

# Fees Engine billing package examples

> Walk through end-to-end billing package examples for boleto tiered pricing, volume discounts, and account maintenance charges with full JSON configuration.

<Tip>
  This page is business-oriented — it focuses on *what* each billing model solves and *how* to configure it. For field-level details, see the [Billing Packages overview](/en/midaz/fees/fees-engine-overview#billing-packages) and the [API reference](/en/reference/midaz/plugins/fees-engine/create-billing-package).
</Tip>

## Volume billing: boleto issuance with tiered pricing

***

### The business need

A fintech offers boleto issuance to its business clients. Pricing is volume-based: the more boletos a client issues each month, the lower the unit cost. The first 50 boletos each month are free. Clients that issue 1,000 or more boletos receive an extra 5% discount. At 3,000 boletos or more, the discount increases to 10%.

### Pricing structure

| Range     | Unit price |
| --------- | ---------- |
| 1–500     | R\$ 1.20   |
| 501–2,000 | R\$ 0.80   |
| 2,001+    | R\$ 0.45   |

### Package configuration

```json theme={null}
POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "Boleto Issuance — Tiered",
  "description": "Monthly volume billing for boleto issuance with progressive tiers",
  "ledgerId": "ldg_01HZ...",
  "type": "volume",
  "enable": true,
  "eventFilter": {
    "transactionRoute": "boleto-issuance",
    "status": "APPROVED"
  },
  "pricingModel": "tiered",
  "tiers": [
    { "minQuantity": 1, "maxQuantity": 500, "unitPrice": "1.20" },
    { "minQuantity": 501, "maxQuantity": 2000, "unitPrice": "0.80" },
    { "minQuantity": 2001, "maxQuantity": null, "unitPrice": "0.45" }
  ],
  "freeQuota": 50,
  "discountTiers": [
    { "minQuantity": 1000, "discountPercentage": "5.00" },
    { "minQuantity": 3000, "discountPercentage": "10.00" }
  ],
  "countMode": "perRoute",
  "assetCode": "BRL",
  "debitAccountAlias": "client-operating",
  "creditAccountAlias": "fees-boleto-revenue"
}
```

### How the calculation works

At month-end, the orchestrator calls `POST /v1/billing/calculate` with the billing period. The engine counts approved boleto transactions on the route, subtracts the free quota, applies tiered pricing, and applies the matching discount.

Tiered pricing is **volume pricing**: the engine picks the single tier the billable count lands in and charges every billable unit at that tier's price. It does not bill each tier's slice separately.

**Example result** — a client that issued 1,800 boletos in March:

| Step          | Detail                   | Amount           |
| ------------- | ------------------------ | ---------------- |
| Total issued  | 1,800 boletos            | —                |
| Free quota    | 50 exempt                | —                |
| Billable      | 1,750 boletos            | —                |
| Matching tier | 501–2,000 → R\$ 0.80     | —                |
| Gross         | 1,750 × R\$ 0.80         | R\$ 1,400.00     |
| Discount      | 5% (total count ≥ 1,000) | −R\$ 70.00       |
| **Net total** | —                        | **R\$ 1,330.00** |

The engine returns a transaction payload that debits `client-operating` by R\$ 1,330.00 and credits `fees-boleto-revenue`.

## Maintenance billing: monthly account fee (*PF*)

***

### The business need

A digital bank charges a fixed monthly maintenance fee for active personal (PF) accounts. The fee is R\$ 9.90 per account. The engine keeps only accounts whose status code is `active` and excludes every other status. You do not filter them by hand.

Midaz organizes accounts by segment. The segment `seg_pf` groups all personal accounts.

### Package configuration

```json theme={null}
POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "PF Account Maintenance",
  "description": "Monthly maintenance fee for active personal accounts",
  "ledgerId": "ldg_01HZ...",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "9.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pf",
  "accountTarget": {
    "segmentId": "seg_pf_01HZ..."
  }
}
```

### How the calculation works

The engine resolves all accounts in the PF segment and filters for active status. It generates one N:1 transaction: it debits R\$ 9.90 from each active account and sends the full total to `fees-maintenance-pf`.

**Example result** — 12,000 active PF accounts:

| Detail                            | Value                |
| :-------------------------------- | :------------------- |
| Active accounts                   | 12,000               |
| Fee per account                   | R\$ 9.90             |
| Transaction entries (source)      | 12,000 debit entries |
| Transaction entries (destination) | 1 credit entry       |
| **Total revenue**                 | **R\$ 118,800.00**   |

## Volume billing: fixed-price Pix with segment exemption

***

### The business need

A fintech charges R\$ 0.10 per Pix sent — flat rate, no tiers. Premium-tier customers pay no fee. Instead of listing each premium account, you configure the exemption at the segment level.

### Package configuration

```json theme={null}
POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "Pix Send — Standard",
  "description": "Flat-rate billing per Pix sent",
  "ledgerId": "ldg_01HZ...",
  "type": "volume",
  "enable": true,
  "eventFilter": {
    "transactionRoute": "pix-send",
    "status": "APPROVED"
  },
  "pricingModel": "fixed",
  "tiers": [
    { "minQuantity": 1, "maxQuantity": null, "unitPrice": "0.10" }
  ],
  "freeQuota": 0,
  "discountTiers": [],
  "countMode": "perRoute",
  "assetCode": "BRL",
  "debitAccountAlias": "client-wallet",
  "creditAccountAlias": "fees-pix-revenue"
}
```

### Segment exemption

To exempt premium accounts, configure the fee package for the `pix-send` route. Add a segment reference to `waivedAccounts`:

```json theme={null}
{
  "waivedAccounts": [
    "segment:seg_premium_01HZ..."
  ]
}
```

All accounts in the premium segment are exempt automatically. When accounts join or leave the segment in Midaz, the change takes effect on the next calculation. You do not update the package.

### How the calculation works

**Example result** — 5,000 Pix transactions from standard accounts:

| Detail         | Value          |
| :------------- | :------------- |
| Total Pix sent | 5,000          |
| Unit price     | R\$ 0.10       |
| **Total**      | **R\$ 500.00** |

Premium accounts show zero charges in the billing results.

## Maintenance billing: PJ portfolios with different rates

***

### The business need

A financial institution manages multiple business (PJ) account portfolios: PME (small and medium enterprises) and Corporate. Each portfolio has a different monthly maintenance fee. The institution wants to calculate both in a single billing run.

### Package configuration

**PME portfolio — R\$ 29.90/month:**

```json theme={null}
POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "PJ Maintenance — PME",
  "description": "Monthly maintenance for PME business accounts",
  "ledgerId": "ldg_01HZ...",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "29.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pj",
  "accountTarget": {
    "portfolioId": "port_pme_01HZ..."
  }
}
```

**Corporate portfolio — R\$ 89.90/month:**

```json theme={null}
POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "PJ Maintenance — Corporate",
  "description": "Monthly maintenance for Corporate business accounts",
  "ledgerId": "ldg_01HZ...",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "89.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pj",
  "accountTarget": {
    "portfolioId": "port_corp_01HZ..."
  }
}
```

### How the calculation works

A single call to `POST /v1/billing/calculate` with `"type": "maintenance"` processes both packages. The response includes one result per package and a consolidated summary.

**Example result** — 500 PME accounts + 50 Corporate accounts:

| Portfolio        | Active accounts | Fee       | Total             |
| ---------------- | --------------- | --------- | ----------------- |
| PME              | 500             | R\$ 29.90 | R\$ 14,950.00     |
| Corporate        | 50              | R\$ 89.90 | R\$ 4,495.00      |
| **Consolidated** | **550**         | —         | **R\$ 19,445.00** |

Both results credit the same `fees-maintenance-pj` account, keeping revenue consolidated. The orchestrator sends each transaction payload to Midaz independently.

## Next steps

***

<CardGroup cols={2}>
  <Card title="Create a billing package" icon="plus" href="/en/reference/midaz/plugins/fees-engine/create-billing-package">
    API reference for creating volume and maintenance billing packages.
  </Card>

  <Card title="Calculate billing" icon="calculator" href="/en/reference/midaz/plugins/fees-engine/calculate-billing">
    Trigger billing calculations for a period and retrieve transaction payloads.
  </Card>

  <Card title="Billing calculations" icon="chart-line" href="/en/midaz/fees/fee-engine-calculation#billing-calculations">
    Detailed mechanics of tiered pricing, free quotas, and maintenance billing.
  </Card>

  <Card title="Best practices" icon="shield-check" href="/en/midaz/fees/fees-engine-best-practices">
    Operational guidance for billing packages in production.
  </Card>
</CardGroup>