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

# Refunds

> How a refund claws back a partner's commission, before or after it was paid out.

When Jane gets her \$49.00 back, Sam should not keep the commission. Tolt reverses it for you, and how depends on whether it was already paid.

 txn\_6Bv2Mq… \$49.00
refunded
 Tolt

Not paid out yet

**commission**comm\_7XqLm2Kw…typesaleamount0statusrefunded

Already paid out

**commission**comm\_9LpR4tWz…typerefundamount-1470statusapproved

The negative commission nets against Sam's next payout.

Paid commissions are never edited, so your payout history stays accurate. The clawback shows up as its own line.

## Refunds from billing integrations

If Stripe, Paddle or Chargebee is connected, you do nothing. Tolt receives the refund from your billing provider and reverses the commission automatically.

> [!WARNING]
>
> Don't also call the refund endpoint for payments a billing integration already tracks. You only need the API for transactions you created with `POST /v2/transactions`.

## Refund through the API

Refund the Tolt transaction by its `txn_` id. The whole transaction is refunded and every commission on it is reversed.

```ts TypeScript theme={"system"}
import { ToltApiClient } from "@tolt/api";

const tolt = new ToltApiClient({ token: process.env.TOLT_API_KEY! });

const { data: txn } = await tolt.transactions.refund({
  id: "txn_6Bv2MqXr9LtWc4ZnKd8pHy3s",
});
console.log(txn.status); // "refunded"
```

```python Python theme={"system"}
import os
from tolt import ToltApi

client = ToltApi(token=os.environ["TOLT_API_KEY"])

txn = client.transactions.refund(id="txn_6Bv2MqXr9LtWc4ZnKd8pHy3s").data
print(txn.status)  # "refunded"
```

```bash cURL theme={"system"}
ID=txn_6Bv2MqXr9LtWc4ZnKd8pHy3s
curl -X POST \
  "https://platform.tolt.com/v2/transactions/$ID/refund" \
  -H "Authorization: Bearer $TOLT_API_KEY"
```

Refunding the same transaction twice returns `409 transaction_refunded`.

> **Finding the transaction from your charge id**
>
> If you stored your own charge id when you created the transaction, search for it:
>
> ```bash theme={"system"}
> curl -G https://platform.tolt.com/v2/transactions \
>   -d search=ch_3PqL8vXk2Rt \
>   -H "Authorization: Bearer $TOLT_API_KEY"
> ```
>
> Or save the `txn_` id from the `POST /v2/transactions` response next to the charge in your database, so refunds need no lookup.

## React to refunds

A refund fires `transaction.updated` with `status: "refunded"`. Use it to update your own records or notify the partner.

```ts theme={"system"}
switch (event.type) {
  case "transaction.updated":
    if (event.data.status === "refunded") {
      await markRefunded(event.data.id);
    }
    break;
}
```

See [Sync your data](/guides/sync-data) for a complete, verified webhook handler.

> [!TIP]
>
> Set a delayed approval (for example 30 days) on your flows to match your refund window. Most refunds then land before anything is paid, and no clawback is needed. See [Approve commissions](/guides/approve-commissions).


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