> ## Documentation Index
> Fetch the complete documentation index at: https://developers.staging01.melio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Fee Calculator

> Estimate the fees for a prospective payment before you create it.

The fee calculator estimates the fees for a payment between two of an entity's accounts **without creating a payment**. Use it to show a business the cost of a payment up front, or to compare the fees of different delivery preferences.

Fees depend on four things: the originating (debit) account, the receiving (credit) account, the `deliveryPreference`, and the `amount`.

```text theme={null}
POST /tools/fee-calculator
```

**Authentication:** API key (`Authorization: Bearer <api-key>`). **Required header:** `Melio-Entity-Id` - the entity that owns the accounts, either an entity id (`ent_<uuid>`) or `me` for the partner's sole entity.

<Note>
  All monetary values in the Payouts API are in **minor units** (cents). An `amount` of `125000` means \$1,250.00. See [Timestamps](/docs/timestamps) for the related date conventions.
</Note>

## Request

| Field                  | Type    | Required | Description                                                                  |
| ---------------------- | ------- | -------- | ---------------------------------------------------------------------------- |
| `originatingAccountId` | string  | Yes      | Internal originating account id (`acct_<id>`), the debit account.            |
| `receivingAccountId`   | string  | Yes      | External receiving account id (`acct_<id>`), the credit account.             |
| `deliveryPreference`   | string  | Yes      | The delivery preference to price. Its rail must match the receiving account. |
| `amount`               | integer | Yes      | The payment amount to price, in minor units (cents).                         |
| `currency`             | string  | No       | Defaults to `USD`.                                                           |

`deliveryPreference` is one of: `standard-ach`, `same-day-ach`, `rtp`, `standard-check`, `express-check`, `overnight-check`, `domestic-wire`, `instant-domestic-wire`, `virtual-card`, `instant-virtual-card`. The normal-speed values (`standard-ach`, `standard-check`, `domestic-wire`, `virtual-card`) price the rail at normal speed.

### Example request

```bash theme={null}
curl -X POST https://api.example.com/v2/tools/fee-calculator \
  -H "Authorization: Bearer <api-key>" \
  -H "Melio-Entity-Id: me" \
  -H "Content-Type: application/json" \
  -d '{
    "originatingAccountId": "acct_3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "receivingAccountId": "acct_9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "deliveryPreference": "same-day-ach",
    "amount": 125000
  }'
```

## Response

The response is an array of the fees that would apply. Each `Fee` describes both how the fee is defined (`fixed` or `percent`) and, where possible, the resolved `amount` for the requested payment.

```json theme={null}
[
  {
    "type": "expedited-ach",
    "chargeTo": "originator",
    "percent": { "rate": 0.5, "max": 3000 },
    "amount": 625
  }
]
```

In this example the fee is 0.5% of the $1,250.00 payment = $6.25 (`625` cents), which is below the \$30.00 cap (`max: 3000`), charged to the originator.

| Field                         | Description                                                                                                                                         |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                        | The fee category (for example `ach`, `card`, `expedited-ach`).                                                                                      |
| `chargeTo`                    | Which side pays the fee: `originator` or `receiver`.                                                                                                |
| `fixed.value`                 | Present when the fee is a flat amount (cents).                                                                                                      |
| `percent.rate`                | Percentage rate (for example `2.9` = 2.9%).                                                                                                         |
| `percent.min` / `percent.max` | Optional floor and cap on the percentage fee (cents).                                                                                               |
| `amount`                      | The resolved fee for the requested amount (cents). Absent only when it cannot be resolved without a per-payment quote (for example tiered pricing). |

## Errors

| Status | When                                                                                      |
| ------ | ----------------------------------------------------------------------------------------- |
| `400`  | Validation error, an invalid account type, or the fee engine could not price the request. |
| `404`  | The entity or an account was not found.                                                   |

See [Errors](/docs/errors) for the response shape.

## Related tools

* [Eligibility](/docs/eligibility) - which fast delivery options a payment qualifies for.
* [Delivery ETA](/docs/delivery-eta) - when a payment would be delivered.