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.

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 and the API reference.

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

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

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

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:

{
  "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:

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:

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

---

Create a billing package

API reference for creating volume and maintenance billing packages.

Calculate billing

Trigger billing calculations for a period and retrieve transaction payloads.

Billing calculations

Detailed mechanics of tiered pricing, free quotas, and maintenance billing.

Best practices

Operational guidance for billing packages in production.