Refunds

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… refunded Tolt

Not paid out yet

commissioncomm_7XqLm2Kw…

typesale

amount0

statusrefunded

Already paid out

commissioncomm_9LpR4tWz…

typerefund

amount-1470

statusapproved

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.

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.

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"

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"

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:

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.

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

See Sync your data for a complete, verified webhook handler.

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.

Get started

Track conversions

Integrations

Concepts

Run your program

Guides

Refunds from billing integrations

Refund through the API

React to refunds

​Refunds from billing integrations

​Refund through the API

​React to refunds

Refunds from billing integrations

Refund through the API

React to refunds