Fees Engine billing package examples

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 more than 1,000 boletos receive an extra 5% discount. Above 3,000 boletos, 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": "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. The engine excludes inactive, closed, or suspended accounts automatically. 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": "perAccount",
  "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.

Midaz Core

CRM

Fees

Fees Engine billing package examples

Volume billing: boleto issuance with tiered pricing

The business need

Pricing structure

Package configuration

How the calculation works

Maintenance billing: monthly account fee (PF)

The business need

Package configuration

How the calculation works

Volume billing: fixed-price Pix with segment exemption

The business need

Package configuration

Segment exemption

How the calculation works

Maintenance billing: PJ portfolios with different rates

The business need

Package configuration

How the calculation works

Next steps

Create a billing package

Calculate billing

Billing calculations

Best practices

​Volume billing: boleto issuance with tiered pricing

​The business need

​Pricing structure

​Package configuration

​How the calculation works

​Maintenance billing: monthly account fee (PF)

​The business need

​Package configuration

​How the calculation works

​Volume billing: fixed-price Pix with segment exemption

​The business need

​Package configuration

​Segment exemption

​How the calculation works

​Maintenance billing: PJ portfolios with different rates

​The business need

​Package configuration

​How the calculation works

​Next steps

Create a billing package

Calculate billing

Billing calculations

Best practices

Volume billing: boleto issuance with tiered pricing

The business need

Pricing structure

Package configuration

How the calculation works

Maintenance billing: monthly account fee (PF)

The business need

Package configuration

How the calculation works

Volume billing: fixed-price Pix with segment exemption

The business need

Package configuration

Segment exemption

How the calculation works

Maintenance billing: PJ portfolios with different rates

The business need

Package configuration

How the calculation works

Next steps