---
referrals: 3
kind: program
payer: domain:acme.example
code: acme_tier
category: saas
status: open
at: 2026-10-30T00:00:00Z
crit: tiered
---
# Acme volume tiers

Rates, amounts and names in this file are placeholders, not recommendations or market rates. Each party sets its own terms.

In plain words: a referrer earns 7% of its revenue for the year, and 11% of all of it once the year's total reaches 50,000.00. A refund can bring the rate back down, and the amounts follow.

Change first: `payer`, `code`, the tiers and the period. Use `mode: marginal` if each rate should apply only to the slice inside its tier.

## Rules

### yearly_tier

- on: payment
- basis: tiered
- of: amount
- measure: revenue
- mode: retroactive
- period: year

| from | rate |
|---|---|
| 0 | 7% |
| 50000 | 11% |

## Attribution

- model: last_touch
- window_days: 30
- customer_lock_days: 365
- allowed_kinds: link, code

## Settlement

- holdback_days: 30
- clawback_days: 90
- cycle: quarterly
- payout_asset: USD
- rails: ach

## Example

Made-up lines. Payments of 30,000.00 in January and February cross the line, so February lifts the whole year to 11%. A refund of 20,000.00 drops the total below it. A March payment crosses it again.

To run it, save this file as `REFERRALS.md` and these lines as `referrals.jsonl`, then run `node referrals.mjs run REFERRALS.md referrals.jsonl --as-of 2027-07-01T00:00:00Z`.

As of: 2027-07-01T00:00:00Z

```jsonl
{"type":"agreement","code":"alice","partner":"domain:alice.example"}
{"type":"event","at":"2027-01-15T10:00:00Z","kind":"payment","source":"billing:inv_401","customer":"cu_708192a3b4c5d6e7","amount":"30000.00","asset":"USD","token":"rf1.acme_tier.alice"}
{"type":"event","at":"2027-02-15T10:00:00Z","kind":"payment","source":"billing:inv_402","customer":"cu_708192a3b4c5d6e7","amount":"30000.00","asset":"USD"}
{"type":"event","at":"2027-02-28T10:00:00Z","kind":"refund","source":"billing:re_402","customer":"cu_708192a3b4c5d6e7","amount":"20000.00","asset":"USD","reverses":"ev_f20b780708eff8fe1b672424"}
{"type":"event","at":"2027-03-15T10:00:00Z","kind":"payment","source":"billing:inv_403","customer":"cu_708192a3b4c5d6e7","amount":"30000.00","asset":"USD"}
```

## Worked result

Computed by `run_ledger` as of 2027-07-01T00:00:00Z, on the made-up lines above. Computed amounts are arithmetic on the records and terms you sent. They do not say what anyone owes. Your contract decides that.

| Event | Who | Working | Computed | Note |
|---|---|---|---|---|
| payment, 2027-01-15 | alice | 7% of a period total of 30000.00, less what the period has so far | 2100.00 | disclosure_unstated |
| payment, 2027-02-15 | alice | 11% of a period total of 60000.00, less what the period has so far | 4500.00 | disclosure_unstated |
| refund, 2027-02-28 | alice | 7% of a period total of 40000.00, less what the period has so far | -3800.00 |  |
| payment, 2027-03-15 | alice | 11% of a period total of 70000.00, less what the period has so far | 4900.00 | disclosure_unstated |

`disclosure_unstated`: The token doesn't say whether this touch was disclosed. A short link proves nothing about that, and the referrer still carries the duty.

| Payee | Asset | Earned | Reversed | Net | Held | Payable |
|---|---|---|---|---|---|---|
| alice | USD | 11500.00 | -3800.00 | 7700.00 | 0.00 | 7700.00 |


## Why these settings

`retroactive` matches a contract that says "the whole year at the rate you reached", and a reversal recomputes the year's target, so the same revenue gives the same amount whichever invoice was refunded.