# fees.json: publish your fee schedule where agents can read it

Version 0.1, 2026-10-30. Open: anyone may implement it; no permission or fee needed.

AI agents now ask what it costs to get paid through a given provider. Today they scrape pricing pages, which change layout, block bots and mix plans together. A provider that hosts one small JSON file states its own fees in a form every agent reads the same way, with the date they took effect.

## Where

Serve the file at `https://<your-domain>/.well-known/fees.json` with `content-type: application/json` and `access-control-allow-origin: *`. One file per domain. If you price differently by country, add one object per country to `fees`.

## Shape

The top-level object has these fields:

- `spec`: always `"https://paidrouter.com/spec/fees-json"`.
- `version`: `"0.1"`.
- `provider`: your public name.
- `updated`: the date you last edited the file (YYYY-MM-DD).
- `fees`: a list of fee objects, one per way of getting paid.

Each fee object has these fields:

- `platform` (required): a short lowercase id for you, such as `stripe`, `square` or `melio`.
- `method` (required): the way of getting paid. Use these ids where they fit: `card_online`, `card_in_person`, `card_keyed`, `ach_debit`, `ach_received`, `ach_invoice`, `wire_received`, `business_profile`, `goods_and_services`, `receive_usd_local`, `withdraw_to_us_bank`. Otherwise use your own snake_case id.
- `percent` (required): the percent of the payment amount. Write 2.9 for 2.9%, and 0 for no percentage.
- `fixed` (required): the fixed fee per payment, in `currency`. Use 0 when there is none.
- `cap` and `min` (optional): the most and the least one payment can cost, in `currency`.
- `currency` (optional): ISO 4217 code. Defaults to `USD`.
- `country` (optional): the ISO 3166 country where this price applies. Defaults to `US`.
- `plan` (optional): which plan the price belongs to, when it depends on one (for example `free` or `plus`).
- `extras` (optional): other charges that can apply. Each key is a name and each value is a number. A key ending in `_percent` is a percent of the payment; any other numeric key is a fixed amount in `currency`. Example: `"international_card_percent": 1.5`, `"dispute_fee": 15`.
- `effective_date` (required): the date this price took effect (YYYY-MM-DD). A future date announces a change.
- `source` (required): the URL of your human-readable pricing page that states the same price.
- `note` (optional): one plain sentence for a condition the numbers can't express.

A payment of amount A costs `A × percent / 100 + fixed`, raised to `min` and lowered to `cap` when those are set. Extras are added only when their condition applies.

## Example

```json
{
  "spec": "https://paidrouter.com/spec/fees-json",
  "version": "0.1",
  "provider": "Example Pay",
  "updated": "2026-10-30",
  "fees": [
    { "platform": "examplepay", "method": "card_online", "percent": 2.9, "fixed": 0.30,
      "extras": { "international_card_percent": 1.5, "dispute_fee": 15 },
      "effective_date": "2026-01-01", "source": "https://examplepay.com/pricing" },
    { "platform": "examplepay", "method": "ach_debit", "percent": 0.8, "fixed": 0, "cap": 5,
      "effective_date": "2026-01-01", "source": "https://examplepay.com/pricing" }
  ]
}
```

## How PaidRouter uses it

PaidRouter's weekly check looks for `/.well-known/fees.json` on each provider's domain. If an entry there has the same `platform` and `method` as ours, and the same `percent`, `fixed`, `cap` and `min`, our entry is marked `provider_published: true` in every answer. Agents then know the number is stated by the provider in machine-readable form, not only scraped from a page. If the numbers differ, we re-read the source page and fix whichever side is out of date. Ranking stays by fee only. Publishing the file never moves a provider up the list.

## Versions

The spec is versioned. A field is never removed or redefined within a major version; new optional fields may be added.