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

# Using account plans

> Create an account plan, assign it to an account, read the fee of each transaction and the usage of the month, and charge service fees.

This guide creates an account plan with one transaction fee and one service fee, and uses it on one account. [Account plans](https://docs.lerian.studio/en/products/midaz/fees/account-plans.md) gives the rules that the steps follow.

## Before you start

***

You need:

* A ledger and an account for the customer, here with the alias `@customer_001`.
* An account that receives the fees, here with the alias `@fee_revenue`.
* The `account-plans` and `fee-charges` permissions on Midaz. See [Permissions](https://docs.lerian.studio/en/products/midaz/fees/account-plans.md#permissions).

The examples use a ledger without route validation, where a transaction fee selects transactions by `scheme`. On a ledger with route validation, give each fee an `accounting` block too. See [Accounting routes](https://docs.lerian.studio/en/products/midaz/fees/account-plans.md#accounting-routes).

The examples use these shell variables. Every UUID is a placeholder. Use the values from your own environment.

```bash theme={null}
MIDAZ_LEDGER_URL="https://midaz.example.com"
MIDAZ_BEARER_TOKEN="..."
MIDAZ_ORGANIZATION_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"
MIDAZ_LEDGER_ID="9c858901-8a57-4791-81fe-4a34d4dd8ab5"
MIDAZ_ACCOUNT_ID="0199a5c1-3e2f-7b4d-9a8e-5f6d7c8b9a0e"   # the account of @customer_001
```

**1. Create the account plan**

Send the plan to [Create an account plan](https://docs.lerian.studio/en/reference/products/midaz/v2/create-an-account-plan.md). The fee `tedSent` charges 7.90 for each TED that the account sends, after 2 free TEDs in the month. The fee `paperStatement` charges 3 for each paper statement, after 1 free statement in the month.

```bash theme={null}
curl -s -X POST "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/account-plans" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Essential PF",
    "description": "Essential plan for individuals",
    "enable": true,
    "timezone": "America/Sao_Paulo",
    "fees": {
      "tedSent": {
        "feeLabel": "TED sent",
        "trigger": { "type": "transaction", "schemes": ["TED"], "direction": "sent" },
        "calculationModel": { "applicationRule": "flatFee", "calculations": [{ "type": "flat", "value": "7.90" }] },
        "creditAccount": "@fee_revenue",
        "freeQuota": 2
      },
      "paperStatement": {
        "feeLabel": "Paper statement",
        "trigger": { "type": "service", "serviceCode": "PAPER_STATEMENT" },
        "calculationModel": { "applicationRule": "flatFee", "calculations": [{ "type": "flat", "value": "3" }] },
        "creditAccount": "@fee_revenue",
        "freeQuota": 1
      }
    }
  }'
```

Midaz answers `201` with the plan and its version 1. It fills in the defaults `referenceAmount` and `period`:

```json theme={null}
{
  "id": "019a3b2c-1d4e-7f60-8a9b-0c1d2e3f4a5b",
  "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
  "label": "Essential PF",
  "description": "Essential plan for individuals",
  "enable": true,
  "timezone": "America/Sao_Paulo",
  "currentVersion": 1,
  "version": 1,
  "effectiveFrom": "2026-10-30T13:00:00Z",
  "fees": {
    "paperStatement": {
      "feeLabel": "Paper statement",
      "trigger": { "type": "service", "serviceCode": "PAPER_STATEMENT" },
      "calculationModel": { "applicationRule": "flatFee", "calculations": [{ "type": "flat", "value": "3" }] },
      "referenceAmount": "originalAmount",
      "creditAccount": "@fee_revenue",
      "freeQuota": 1,
      "period": "monthly"
    },
    "tedSent": {
      "feeLabel": "TED sent",
      "trigger": { "type": "transaction", "schemes": ["TED"], "direction": "sent" },
      "calculationModel": { "applicationRule": "flatFee", "calculations": [{ "type": "flat", "value": "7.90" }] },
      "referenceAmount": "originalAmount",
      "creditAccount": "@fee_revenue",
      "freeQuota": 2,
      "period": "monthly"
    }
  },
  "createdAt": "2026-10-30T13:00:00Z",
  "updatedAt": "2026-10-30T13:00:00Z"
}
```

Keep the `id` of the plan:

```bash theme={null}
MIDAZ_ACCOUNT_PLAN_ID="019a3b2c-1d4e-7f60-8a9b-0c1d2e3f4a5b"
```

**2. Assign the plan to the account**

Send the plan to [Assign an account plan to an account](https://docs.lerian.studio/en/reference/products/midaz/v2/assign-an-account-plan-to-an-account.md):

```bash theme={null}
curl -s -X PUT "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/accounts/$MIDAZ_ACCOUNT_ID/account-plan" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{ \"accountPlanId\": \"$MIDAZ_ACCOUNT_PLAN_ID\" }"
```

Midaz answers `200` with the active assignment:

```json theme={null}
{
  "id": "019a3b2d-5e6f-7a80-9b1c-2d3e4f5a6b7c",
  "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
  "accountId": "0199a5c1-3e2f-7b4d-9a8e-5f6d7c8b9a0e",
  "accountAlias": "@customer_001",
  "accountPlanId": "019a3b2c-1d4e-7f60-8a9b-0c1d2e3f4a5b",
  "startedAt": "2026-10-30T13:05:00Z",
  "endedAt": null
}
```

From now on, the fee packages of the ledger do not charge `@customer_001` on the `/v2` transactions it sends.

**3. Send a transaction and read its fee**

Send a TED from the account with [Create a Transaction using the v2 direct model](https://docs.lerian.studio/en/reference/products/midaz/v2/create-transaction-direct.md). The `scheme` is `TED`, so the fee `tedSent` matches:

```bash theme={null}
curl -s -X POST "$MIDAZ_LEDGER_URL/v2/transactions/direct" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency: ted-0001' \
  -d "{
    \"description\": \"TED to another bank\",
    \"asset\": \"BRL\",
    \"amount\": \"100\",
    \"scheme\": \"TED\",
    \"debits\": [
      { \"alias\": \"@customer_001\", \"organizationId\": \"$MIDAZ_ORGANIZATION_ID\", \"ledgerId\": \"$MIDAZ_LEDGER_ID\", \"amount\": \"100\" }
    ],
    \"credits\": [
      { \"alias\": \"@ted_settlement\", \"organizationId\": \"$MIDAZ_ORGANIZATION_ID\", \"ledgerId\": \"$MIDAZ_LEDGER_ID\", \"amount\": \"100\" }
    ]
  }"
```

The `201` response has `accountPlanFees`. The first TED of the month uses a free unit:

```json theme={null}
"accountPlanFees": [
  {
    "accountId": "0199a5c1-3e2f-7b4d-9a8e-5f6d7c8b9a0e",
    "accountAlias": "@customer_001",
    "accountPlanId": "019a3b2c-1d4e-7f60-8a9b-0c1d2e3f4a5b",
    "accountPlanVersion": 1,
    "feeKey": "tedSent",
    "outcome": "quota",
    "unit": 1,
    "freeQuota": 2,
    "amount": "0"
  }
]
```

The third TED of the month is past the free quota. Its item has `"outcome": "charged"`, `"unit": 3`, and `"amount": "7.9"`. The account sends 107.9: the 100 of the TED and the fee, which goes to `@fee_revenue`.

A transaction with another `scheme`, or without one, gets `"outcome": "no_match"`. The account pays no fee on it.

Keep `accountPlanFees` from the create response. The reads of the transaction do not return it.

**4. Read the usage of the month**

Read the units of the account with [Get the account plan usage of an account](https://docs.lerian.studio/en/reference/products/midaz/v2/get-the-account-plan-usage-of-an-account.md):

```bash theme={null}
curl -s "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/accounts/$MIDAZ_ACCOUNT_ID/account-plan/usage?period=2026-10" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN"
```

After three TEDs, the response is:

```json theme={null}
{
  "accountId": "0199a5c1-3e2f-7b4d-9a8e-5f6d7c8b9a0e",
  "accountPlanId": "019a3b2c-1d4e-7f60-8a9b-0c1d2e3f4a5b",
  "accountPlanVersion": 1,
  "period": { "label": "2026-10", "start": "2026-10-01T03:00:00Z", "end": "2026-11-01T03:00:00Z" },
  "items": [
    {
      "feeKey": "paperStatement",
      "trigger": "fee:paperStatement",
      "period": { "label": "2026-10", "start": "2026-10-01T03:00:00Z", "end": "2026-11-01T03:00:00Z" },
      "freeQuota": 1,
      "used": 0,
      "remaining": 1,
      "charged": 0
    },
    {
      "feeKey": "tedSent",
      "trigger": "fee:tedSent:TED",
      "period": { "label": "2026-10", "start": "2026-10-01T03:00:00Z", "end": "2026-11-01T03:00:00Z" },
      "freeQuota": 2,
      "used": 3,
      "remaining": 0,
      "charged": 1
    }
  ]
}
```

`period.start` and `period.end` are the month in the plan timezone, in UTC.

**5. Charge service fees**

Charge two paper statements with [Charge service fees to an account](https://docs.lerian.studio/en/reference/products/midaz/v2/charge-service-fees-to-an-account.md). Send an `X-Idempotency` key, and send the same key when you retry the same charge:

```bash theme={null}
curl -s -X POST "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/accounts/$MIDAZ_ACCOUNT_ID/fee-charges" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency: statements-2026-10' \
  -d '{
    "serviceCodes": ["PAPER_STATEMENT", "PAPER_STATEMENT"],
    "description": "Paper statements of October"
  }'
```

Midaz answers `201`. The first statement uses the free unit, and the second costs 3:

```json theme={null}
{
  "id": "019a3b30-7c8d-7e90-a1b2-c3d4e5f6a7b8",
  "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
  "accountId": "0199a5c1-3e2f-7b4d-9a8e-5f6d7c8b9a0e",
  "accountPlanId": "019a3b2c-1d4e-7f60-8a9b-0c1d2e3f4a5b",
  "accountPlanVersion": 1,
  "description": "Paper statements of October",
  "items": [
    { "serviceCode": "PAPER_STATEMENT", "feeKey": "paperStatement", "outcome": "quota", "unit": 1, "freeQuota": 1, "amount": "0" },
    { "serviceCode": "PAPER_STATEMENT", "feeKey": "paperStatement", "outcome": "charged", "unit": 2, "freeQuota": 1, "amount": "3" }
  ],
  "totalAmount": "3",
  "assetCode": "BRL",
  "feeTransactionIds": ["019a3b30-8d9e-7fa0-b2c3-d4e5f6a7b8c9"],
  "period": "2026-10",
  "createdAt": "2026-10-30T14:00:00Z"
}
```

The fee transaction debits 3 from `@customer_001` and credits it to `@fee_revenue`. To undo the charge in the same month, revert that transaction.

**6. Create a new version**

Raise the free TEDs to 5 from November. Send only the field that changes to [Update an account plan](https://docs.lerian.studio/en/reference/products/midaz/v2/update-an-account-plan.md):

```bash theme={null}
curl -s -X PATCH "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/account-plans/$MIDAZ_ACCOUNT_PLAN_ID" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "fees": { "tedSent": { "freeQuota": 5 } },
    "effectiveFrom": "2026-11-01T03:00:00Z"
  }'
```

Midaz creates version 2 with both fees, and `tedSent` has `freeQuota: 5`. Before November 1 in the plan timezone, the response and the transactions use version 1, and `currentVersion` is `2`.

**7. End the assignment**

To take the account off the plan, use [End the account plan assignment of an account](https://docs.lerian.studio/en/reference/products/midaz/v2/end-the-account-plan-assignment-of-an-account.md):

```bash theme={null}
curl -s -X DELETE "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/accounts/$MIDAZ_ACCOUNT_ID/account-plan" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN"
```

Midaz answers `204`. The fee packages of the ledger apply to the account again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.