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

# Fee rules

> Model expected transaction fees so Matcher adjusts amounts before comparison and avoids false exceptions on predictable charges.

Fee rules define how Matcher calculates and applies fees during the reconciliation process. Use fee rules to model transaction fees, service charges, and expected deductions that affect matching outcomes.

## What fee rules solve

***

Reconciliation fails when one side of a transaction includes fees or charges that the other side doesn't record. A payment gateway deducts a processing fee before settling. A bank charges a wire transfer fee. An acquirer nets fees against payouts.

Without fee rules, Matcher treats these differences as amount mismatches and generates exceptions — even when the difference is expected and documented. Fee rules tell Matcher what fees to anticipate, so it can match correctly despite the amount difference.

## How fee rules work

***

Fee rules are attached to a reconciliation context. When Matcher runs, it evaluates applicable fee rules and adjusts expected amounts before comparing transactions across sources.

This adjustment happens before match rule evaluation. A transaction that would otherwise fall outside tolerance can match cleanly once the known fee is accounted for.

Fee rules reduce false exceptions caused by predictable, recurring charges. Instead of manually resolving hundreds of expected fee differences each day, your team focuses on real discrepancies.

## Fee rule structure

***

| Field                  | Description                                                                                                    |
| ---------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Name**               | Descriptive label for the fee rule. Use names that identify the fee origin (e.g., "Gateway processing fee").   |
| **Type**               | The category of fee: `processing`, `service_charge`, `wire_fee`, `acquirer_fee`, or `custom`.                  |
| **Calculation method** | How the fee is computed: `flat` (fixed amount) or `percentage` (percentage of transaction amount).             |
| **Amount / Rate**      | The fee value. For flat fees, the fixed amount. For percentage fees, the rate (e.g., `2.5` for 2.5%).          |
| **Applied to**         | Which side of the match to adjust: the source transaction, the target transaction, or both.                    |
| **Conditions**         | Optional filters that restrict when the rule applies — by source, amount range, currency, or transaction type. |
| **Active**             | Whether the rule is currently in use. Inactive rules are retained but not evaluated.                           |

## Creating a fee rule

***

This example creates a fee rule for a payment gateway that deducts a 2.5% processing fee from settlements before crediting the merchant account.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/fee-rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gateway processing fee — 2.5%",
    "type": "processing",
    "calculationMethod": "percentage",
    "rate": 2.5,
    "appliedTo": "target",
    "conditions": {
      "sourceId": "src_gateway_001",
      "currencyCode": "BRL"
    },
    "active": true
  }'
```

<Tip>API Reference: [Create fee rule](/en/reference/matcher/create-fee-rule)</Tip>

## Managing fee rules

***

| Operation               | Description                                                                             |
| ----------------------- | --------------------------------------------------------------------------------------- |
| **List fee rules**      | Retrieve all fee rules for a context, with optional filters.                            |
| **Retrieve a fee rule** | Get the full configuration of a specific fee rule by ID.                                |
| **Update a fee rule**   | Modify rate, conditions, or status without recreating the rule.                         |
| **Delete a fee rule**   | Remove a fee rule permanently. Consider deactivating instead to preserve audit history. |

<Tip>API Reference: [List fee rules](/en/reference/matcher/list-fee-rules) · [Retrieve fee rule](/en/reference/matcher/retrieve-fee-rule) · [Update fee rule](/en/reference/matcher/update-fee-rule) · [Delete fee rule](/en/reference/matcher/delete-fee-rule)</Tip>

## Best practices

***

<AccordionGroup>
  <Accordion title="Start with your highest-volume fees">
    Identify the fee types that generate the most exceptions today. Model those first. A single well-configured fee rule covering a common charge eliminates more manual work than five rules covering edge cases.
  </Accordion>

  <Accordion title="Use descriptive names">
    Names like "Gateway processing fee — 2.5%" are more useful than "Fee rule 1". When reviewing exceptions or auditing matches, a clear name tells the story without opening the configuration.
  </Accordion>

  <Accordion title="Review fee rules when contracts change">
    Fee rates change when payment contracts are renegotiated. A fee rule with an outdated rate generates exceptions instead of preventing them. Schedule a quarterly review — or trigger one whenever a payment partner contract is renewed.
  </Accordion>

  <Accordion title="Use conditions to scope rules precisely">
    A fee rule without conditions applies to all transactions in the context. Narrow rules with source filters, currency codes, or amount ranges prevent unintended adjustments. Broad rules are harder to audit.
  </Accordion>

  <Accordion title="Validate against a sample before enabling">
    Before activating a new fee rule in production, run it against a sample of recent transactions. Confirm it resolves the expected exceptions without creating new ones. Deactivate rather than delete rules you're not sure about — you can reactivate without reconfiguring.
  </Accordion>
</AccordionGroup>

## Next steps

***

<CardGroup cols={2}>
  <Card title="Match rules" icon="scale-balanced" href="/en/matcher/configuration/matcher-match-rules">
    Confidence scoring accounts for fee adjustments when evaluating match quality.
  </Card>

  <Card title="Exception routing" icon="route" href="/en/matcher/configuration/matcher-exception-routing">
    Route the exceptions that fee rules don't cover to the right teams.
  </Card>

  <Card title="Fee rules API reference" icon="code" href="/en/reference/matcher/create-fee-rule">
    Full API reference for fee rule endpoints.
  </Card>
</CardGroup>