> ## 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 real billing-package scenarios, from boleto tiered pricing to maintenance charges, with full configuration examples.

<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/plugins/fees-engine/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 per month, the lower the unit cost. The first 50 boletos each month are complimentary. Clients issuing over 1,000 boletos receive an additional 5% discount; above 3,000, 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": "perAccount",
  "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 per account, subtracts the free quota, applies tiered pricing, and applies the matching discount.

**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        | —                |
| Tier 1       | 500 × R\$ 1.20       | R\$ 600.00       |
| Tier 2       | 1,250 × R\$ 0.80     | R\$ 1,000.00     |
| Subtotal     | —                    | R\$ 1,600.00     |
| Discount     | 5% (> 1,000 boletos) | −R\$ 80.00       |
| **Total**    | —                    | **R\$ 1,520.00** |

The engine returns a transaction payload that debits `client-operating` by R\$ 1,520.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. Inactive, closed, or suspended accounts are excluded automatically — no manual filtering required.

Accounts are organized by segment in Midaz. 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, filters for active status, and generates a single N:1 transaction: each active account is debited R\$ 9.90, and the full total goes 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 are fully exempt from this fee. Instead of listing each premium account individually, the exemption is configured 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": "perAccount",
  "assetCode": "BRL",
  "debitAccountAlias": "client-wallet",
  "creditAccountAlias": "fees-pix-revenue"
}
```

### Segment exemption

To exempt premium accounts, configure the fee package (Motor 1) for the `pix-send` route with a segment reference in `waivedAccounts`:

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

All accounts belonging to the premium segment are exempt automatically. When new accounts join or leave the segment in Midaz, the change takes effect on the next calculation — no package update needed.

### 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/plugins/fees-engine/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/plugins/fees-engine/fees-engine-best-practices">
    Operational guidance for billing packages in production.
  </Card>
</CardGroup>