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

# Fee reporting

> Understand payment-level fee breakdowns and aggregate fee analytics in the Karat Payout API.

The Payout API exposes fee reporting in two places:

* Every payment returned by [`GET /payments`](/api-reference/payments/list-payments) or [`GET /payments/{payment_id}`](/api-reference/payments/get-a-payment) includes a `feeBreakdown`.
* [`GET /payments/fees/analytics`](/api-reference/payments/get-fee-analytics) aggregates completed payments over a date range.

All monetary values are expressed in integer cents unless a field explicitly represents a percentage or average.

## Payment-level fee breakdowns

Use `feeBreakdown.status` before reading the amount fields.

| Status           | Meaning                                                                                                                        |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `RESOLVED`       | Karat found an authoritative fee and fee owner. Amount fields contain numbers, including `0` for a legitimate zero-dollar fee. |
| `PENDING`        | The payment has not reached a terminal state, so its final fee is not available yet. Amount and owner fields are `null`.       |
| `UNRESOLVED`     | The payment completed, but Karat could not yet resolve an authoritative fee record. Amount and owner fields are `null`.        |
| `NOT_APPLICABLE` | The payment failed or was canceled. Amount and owner fields are `null`.                                                        |

<Warning>
  Do not treat a `null` fee as `$0.00`. A resolved zero-dollar fee has `status: "RESOLVED"` and `totalFeeCents: 0`.
</Warning>

For resolved fees:

* `payerFeeCents` is the portion paid by your organization.
* `recipientFeeCents` is the portion deducted from recipient proceeds.
* `paidBy` identifies the fee owner as `PAYER` or `RECIPIENT`.
* `feePercentageOfPaymentAmount` equals `totalFeeCents ÷ payment.amount × 100`.

The `rail` field uses a stable category such as `ACH`, `REAL_TIME_PAYMENT`, `INTERNAL`, `WIRE`, `INTERNATIONAL`, `CRYPTO`, `PAYPAL`, or `OTHER`.

## Aggregate fee analytics

Request analytics with an inclusive start and end date:

```bash theme={null}
curl "https://payouts.api.trykarat.com/payments/fees/analytics?startDate=2026-08-01&endDate=2026-08-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

The endpoint uses these rules:

* Dates are interpreted as UTC calendar days and returned as normalized UTC timestamps.
* The range includes completed, non-external Karat payments whose completion time falls within the range.
* A request can span at most 366 days.
* `paymentVolumeCents` is gross completed payment volume, including zero-fee payments and payments whose fee is unresolved.
* `totalFeeCents` includes resolved fees only.
* `feePercentageOfVolume` equals `totalFeeCents ÷ paymentVolumeCents × 100`.
* `averageFeeCents` equals resolved fees divided by all completed payments in the range.
* `payerFeeCents` and `recipientFeeCents` show who bore the resolved fees.
* `resolvedPaymentCount` and `unresolvedPaymentCount` make the denominator and any incomplete fee resolution visible without changing payment volume.

The same definitions apply to each item in `rails`. Trend points split fees by payer and recipient and also include their combined total.

<Note>
  Fee analytics is released gradually. An organization outside the current rollout receives `403 Forbidden`; contact your Karat representative if you need access.
</Note>

## Empty ranges

When no completed payments fall in the selected range, the endpoint returns a successful response with zero-value summary metrics, zero-value trend buckets, and an empty `rails` array. This lets integrations render a stable empty state without interpreting a `404` as no activity.