Docs menu

Money

Refunding failed calls

Promise buyers their money back when a paid call to your API fails, and see how refunds work from both sides.

Explain it

When you sell calls to your API, you can promise buyers that a call which fails is refunded automatically. It makes buyers more likely to choose you, and your listing shows the promise.

How to do it: open the app's Payments tab and turn on Refund failed calls. A call counts as failed when your app answers with a server error or doesn't answer at all.

You give back what you earned from that call, and CLI gives up its fee on it.

When you sell calls to your API or MCP tools, you can promise buyers that a call which fails is refunded. The buyer gets the whole price back, you give back what you earned from that call, and CLI gives up its fee. Buyers can see the promise in the directory, so it helps you get chosen.

What the guarantee covers

The guarantee covers paid calls to your service's paid routes and MCP tools, whether the buyer paid per call over x402 or from a prepaid stream. A call counts as failed when your app answers with a 5xx status, or doesn't answer at all. Through the MCP gateway, a JSON-RPC answer with an error and no result also counts as failed.

Anything else (a 2xx, a 3xx or a 4xx) is kept.

Turn it on

Turning the guarantee on or off needs a project admin. It applies to calls from then on.

In the dashboard:

  1. Open the service and go to Settings.
  2. Find Refund failed calls.
  3. Press Promise refunds.
  4. Redeploy the service, so your app gets the variables it needs to refund calls itself (see below).

Once it's on, the panel shows the last 30 days: how many guaranteed calls, how many were refunded and for how much, plus a table of recent calls with their outcome.

With the API:

API
PUT /v1/services/:id/guarantee
JSON
{ "enabled": true }

GET /v1/services/:id/guarantee returns the same 30-day figures:

JSON
{
  "enabled": true,
  "calls30": 1840,
  "refunded30": 12,
  "refundedAmount30": 240000,
  "refundRate30": 0.0065
}

Receipts

Every guaranteed call gets a receipt, an id like rcp_4b7e19c02af58d36e1b0. Your app receives it on the request in the X-CLI-Receipt header. Keep it if you might want to refund that call yourself.

Through the MCP gateway the buyer gets the receipt back too, in the response's X-CLI-Receipt header, and X-CLI-Refunded: true when the call was refunded.

List recent receipts and their outcomes (developers and up):

API
GET /v1/services/:id/receipts

Each one says whether it's still waiting for an outcome (open), kept (with the status your app answered) or refunded (with the reason).

How CLI learns a call failed

A receipt stays open for 10 minutes while CLI finds out how the call went. There are three ways:

  1. Calls through the MCP gateway. CLI forwards the call and sees your app's answer itself, so a failure is refunded straight away.
  2. Calls to paid routes. CLI's edge (Traefik) writes an access log line for each request with its receipt and status, and CLI reads those lines (from the shared log file, or as they're posted to POST /v1/edge/outcomes, which only CLI's edge can call). A 5xx in the log refunds the call.
  3. Your app refunds the call. Sometimes a call fails in a way no status code shows, such as a 200 with nothing useful in it. Your app can refund it itself.

A receipt nobody reports a failure for within 10 minutes is closed as kept.

Refund a call from your app

After you turn the guarantee on and redeploy, your app has two variables: CLI_REFUND_URL and CLI_REFUND_TOKEN. To refund a call, send its receipt:

API
POST $CLI_REFUND_URL
Authorization: Bearer $CLI_REFUND_TOKEN
JSON
{ "receipt": "rcp_4b7e19c02af58d36e1b0", "reason": "upstream weather feed returned no data" }
JavaScript
await fetch(process.env.CLI_REFUND_URL, {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.CLI_REFUND_TOKEN}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({ receipt: req.headers["x-cli-receipt"], reason: "no forecast for that location" }),
});

The token only works for receipts of that one service. A refund you give isn't limited to the 10-minute window: you can refund a call that was already kept. Refunding the same call twice gets CONFLICT.

Refund a call by hand

In Refund failed calls, press Refund next to any call that hasn't been refunded. Project members with the developer role or higher can do this.

What a refund does

For the buyer: they get the full price back.

  • If they paid from a prepaid stream, it goes back into that stream's balance, ready for their next call.
  • If they paid per call over x402, it goes back to the wallet that paid. Small refunds are gathered per wallet and network and paid out once they reach $1.

For you, the seller: you give back what you earned from that call: the price less CLI's fee. If the call came from a stream that hadn't been settled to you yet, nothing is taken from your earnings; the stream's spend is undone instead. Refunds show in your earnings as their own source.

For CLI: it gives up its fee on that call.

Each refund raises a call_refunded event on your project, saying how much went back to the buyer and why, so your alert channels can tell you.

The directory badge and ranking

Directory entries for services with the guarantee on show the promise, along with the service's refund rate over the last 30 days.

The promise gives a listing a small lift in search results. A high refund rate costs more than the promise earns, so a service that fails often ranks lower than one with no promise at all. Ranking is never for sale (see /docs/selling-apis).

From the buyer's side

You don't need to do anything to be covered. If the service you call has the guarantee on:

  • calls that fail with a 5xx or no answer are refunded on their own, as soon as CLI learns of the failure;
  • refunds to a stream are available for your next call straight away;
  • refunds for x402 payments come back to your paying wallet once they add up to $1 or more.

Ask your agent:

"Find a weather API that refunds failed calls and has good uptime."

Agents see the guarantee and refund rate in cli_find_api results. To call paid APIs from your own apps, see Paying for other APIs.