---
title: "Safeguards and timing"
description: "What every referral program guards by itself, and every period you can change, with the values to choose."
canonical: "https://boltclaw.ai/docs/referral-safeguards"
last-updated: "2026-11-05"
---

# Safeguards and timing

What every referral program guards by itself, and every period you can change, with the values to choose.

Bolt Claw guards every referral program by itself: you do not build these checks in your
own code. This page lists what is on by default, then every period a program can change,
with its default, its range and the value we recommend for an in-app invite-a-friend
program on a subscription (your own signed-in users invite friends from a panel inside
your product, the friend signs up, then pays monthly). Change them on the program's
[**Settings**, **Timing**](https://boltclaw.ai/dashboard/referrals?open=timing) section,
which shows the same list.

## On by default

- **A referrer's own code is refused when it arrives.** A signup or sale whose referral
  belongs to the customer themselves by what you sent (your `external_id` for the referrer
  equals `customer.id`, or the customer's email is the one you sent for that referrer) is
  not attributed: `attributed: false`, `referral_refused: "self_referral"`, nothing
  earned, nothing to review, and the customer stays free for a real promoter. The program
  counts them ([below](#a-promoters-own-code)).
- **A partner's own email or card is flagged when a reward is at stake.** A partner's
  account or payout address, or the card that paid (known only once it has paid), makes the
  sale wait for you as a `self_referral` flag
  ([the card check](https://boltclaw.ai/docs/referral-fraud#the-card-check)).
- **One card for two friends.** A card that already paid for another customer who had a
  friend's reward makes the later sale wait for you (`friend_reward_repeat`,
  [what stops a reward](https://boltclaw.ai/docs/rewards-not-cash#what-stops-a-reward)).
- **One attribution per customer.** Under first click (the default) a customer belongs to
  the first promoter who brought them; under last click a newer referral from an approved
  promoter takes them over. Either way, conversions already recorded keep their promoter.
- **A late code is refused.** A code typed on a signup more than `late_code_days` after
  Bolt Claw first saw the customer is not applied (`referral_refused: "late_code"`,
  [the friend's welcome](https://boltclaw.ai/docs/referral-welcome)).
- **The hold, and cancellation by a refund or dispute.** Every commission and reward waits
  the program's hold (30 days by default) before it is approved; a refund or dispute in
  that time cancels it ([rewards](https://boltclaw.ai/docs/rewards)).
- **Hold new partners longer.** A promoter's first 90 days add to their risk score and their
  earnings wait 14 days longer ([fraud and risk](https://boltclaw.ai/docs/referral-fraud)).
- **The risk score's holds and the review line.** From a score of 40 money waits longer;
  from 70 it waits for a person. Nothing is rejected, banned or confirmed by a rule
  ([what the score does](https://boltclaw.ai/docs/referral-fraud#what-the-score-does)).
- **A daily cap on signup rewards.** At most `lead_grant_daily_cap` (100) rewards a day for
  signups alone, so invented signups cannot farm credit.
- **A click flood is not counted.** Past 60 clicks from one address in a minute, across
  Bolt Claw, no more are recorded; the redirect still answers.
- **Data-centre clicks are not counted.** Clicks from known data-centre ranges are stored
  and never counted ([what it looks at](https://boltclaw.ai/docs/referral-fraud#what-it-looks-at)).
- **Test data is never paid.** Test conversions and rewards are never payable and never
  counted ([test mode](https://boltclaw.ai/docs/testing)).
- **The friend's reward after a payment.** Refer a friend's default gives the friend's
  month after their first real payment, held and cancelled by a refund like the
  inviter's. If you give it at checkout instead, the offer call checks who it is for and the
  Stripe promotion codes Bolt Claw makes are first-time only. Which checks apply to each:
  [at checkout or after a payment](https://boltclaw.ai/docs/rewards-not-cash#friend-reward-shapes).

## A promoter's own code

The check runs when the event arrives, on any event (a signup, a sale, a checkout your
billing system reports), before anything is decided:

- **What counts as "their own".** Exactly the same person by what you sent: your
  `external_id` for the referrer (live or test) equals the event's `customer.id`, or the
  email the event sent is the one you sent for that referrer (compared as a fingerprint).
  Never a look-alike.
- **What it does not use.** A partner's own account address and any payout address are
  never compared at the event: answering at once would tell whoever reports conversions
  whether a guessed address is a partner's, and a payout mailbox can be a real customer's.
  They still flag the sale for you when a reward is at stake, with their card after a payment
  ([fraud and risk](https://boltclaw.ai/docs/referral-fraud#what-it-looks-at)).
- **What happens.** For a customer nobody holds, the referral is dropped: the conversion is
  recorded as an unreferred one, with `referral_refused` and `attribution_skipped` both
  `self_referral`. No commission, no reward, no flag, and the customer is not attributed,
  so under first click a real promoter can still bring them.
- **A customer already attributed** keeps their promoter: their own code is ignored as any
  second code is.
- **Counting them.** `self_referrals_refused` on
  [`GET /v1/referrals/programs/{id}/stats`](https://boltclaw.ai/docs/api/referrals) (live data, in the
  window), and the program's
  [**Overview**, **Review queue**](https://boltclaw.ai/dashboard/referrals?open=fraud)
  shows the last 30 days' number beside what waits for you.

## Codes people type

A code read aloud, copied from a chat or typed into your product's "Have a code?" field
arrives in many shapes. Bolt Claw reads them all the same way, for `referral.code` on a
conversion and for the offer's `{code}`:

- **Case, spaces and dashes.** `Maya-K3F9`, `maya k3f9` and `MAYA - K3F9` are `maya-k3f9`:
  any case, and any run of spaces or dashes of any kind between groups reads as one hyphen.
- **A missing hyphen.** `mayak3f9`, typed with no hyphen at all, matches `maya-k3f9` when
  it is the only code of the program that is the same without its hyphens. Two codes that
  differ only by hyphens (`ab-cd` and `abcd`) find nothing: Bolt Claw never guesses between
  two people. A hyphen in the wrong place (`may-ak3f9`) is another code.
- **A whole link.** `https://boltclaw.ai/r/maya-k3f9`, a link on your own links domain
  (`go.acme.com/maya-k3f9`) or on your product's site (`?via=maya-k3f9`) gives its code. A
  link on any other site gives nothing. On your own server, `parseTypedCode()` from
  `@boltclaw/referrals` reads a pasted link the same way, so you can send the code itself.
- **What generated codes are made of.** Ten characters from
  `23456789abcdefghjkmnpqrstuvwxyz`: no `0`, `o`, `1`, `i` or `l`, so a code read from a
  screen or said aloud survives. A code you choose for a referrer (a vanity code) is your
  own choice and is matched exactly as chosen, case and spaces apart.
- **Codes made to be typed.** A program's `code_style: typed` makes new codes of 6 to 8
  characters from the same alphabet (`code_length`), or with `code_prefix: name` the
  person's name folded to the letters a to z (at most 8) and four characters (`maya-k3f9`).
  They are shown in capitals (`MAYA-K3F9`) in the panel (`code_display`) and the offer;
  matching ignores case, so it is the same code. It applies to codes made after the change:
  a code already shared never changes. On the program's
  [**Rewards**, **Welcome**](https://boltclaw.ai/dashboard/referrals?open=welcome),
  "Codes people type".

**Every refused code says why.** The conversion is recorded in every case, and
`referral_refused` says what happened to the code, with `referral_refused_message`, a
sentence your product can show in the conversion's `locale`:

| `referral_refused` | What happened |
|---|---|
| `unknown_code` | A code was sent and none of the program's matched it. |
| `inactive_code` | Its link was archived or its discount code switched off. A customer already referred through it keeps their promoter. |
| `too_many_attempts` | The customer (or their network) tried too many unknown codes in the last hour; no code was looked up, a right one included. |
| `late_code` | It came more than `late_code_days` after Bolt Claw first saw the customer. |
| `paid_before` | Under a `first_payment` code window, the customer had already paid. |
| `already_referred` | The customer already has a promoter; another code, typed or not, was not applied. |
| `self_referral` | It was the customer's own code. |

New values may be added: a strict client should accept them.

**Guessing.** A short code can be guessed, so unknown codes (a link code or a discount code
your server sends) are counted: per customer (your `customer.id`, and `customer_id` on the
offer) and, once sign-in fingerprints are kept, per network, across your organisation, for an
hour. Each code is counted before it is looked up, so calls sent at the same moment count
each other. Past 10 a customer or 30 a network, no code is looked up for them at all: the
offer answers `reason_code: too_many_attempts` and a conversion
`referral_refused: too_many_attempts`, for a right code too, until the hour passes, so the
answer never says whether a code exists. A code that matches is never counted. An offer call
without `customer_id` is counted only by your key's own rate limit: send `customer_id`
whenever a person typed the code. Until sign-in fingerprints are kept (they wait for legal
review), the count is per customer only: a person who makes a new account for each guess
starts a new count, and your own sign-up limits are what holds them. A code that matches after its person
tried 5 unknown codes in the hour before scores "Guessed codes" (`code_guessing`, 40, the
hold line), so its reward waits; the number is the fraud settings' `guess_min`.

## A code typed after connecting

Inside an AI assistant the account is made at the connect step, before a friend can type
anything; a friend who hears of the code two days later is refused under the 72 hours a
new program starts with. `code_window: first_payment` fits that:

- A **new** attribution from an event whose `entry` is in `code_window_entries` (null for
  every entry) is taken until the customer's **first paid sale**, within `code_window_days`
  of the account (`customer.created_at`, else when Bolt Claw first saw them).
- A paid sale is one this program recorded live above 0, or your own record sent as
  `customer.first_paid_at`. After it, the code is refused with `paid_before`; past the days,
  with `customer_too_old`. Send `customer.first_paid_at` whenever the program has no
  billing connection of its own: without a sale or your record, Bolt Claw cannot know.
- Inside this window `late_code_days` does not also apply: one window, not two.
- A customer already attributed keeps earning their promoter, as always.
- **One code per customer, ever.** A typed code never takes a customer from another
  promoter, under first click or last click, whatever a page or a document an assistant
  read says (`already_referred`).

**What to choose for a product people sign up to through an AI assistant:**
`code_window: first_payment`, `code_window_days: 30`, `code_window_entries: ["typed"]`
(links keep `new_customer_hours: 72`), and `code_style: typed` with `code_prefix: name`, so
a code is easy to say. Send `entry: "typed"` and `surface: "ai_assistant"` with the lead,
and `customer.first_paid_at` if you record payments yourself. Why: the friend may come back
days later, a month covers that, and nobody who already paid can attach a code.

## What the windows measure

`occurred_at` is when the event happened (the signup, the moment the code was entered, the payment), never when the account was made; without it, it is when Bolt Claw receives the event. The program's `new_customer_hours` compares `occurred_at` with `customer.created_at` (else with when Bolt Claw first saw the customer), so an `occurred_at` set to the account's creation time makes every account look new. `late_code_days` counts from when Bolt Claw first saw the customer to when the event arrives; `occurred_at` does not move it. A promoter's own code is refused by Bolt Claw itself (`referral_refused: "self_referral"`), so your server needs no check of its own.

## Choose: every period

Every period that decides what a promoter or a friend gets. **Where** says where it is
changed: a program setting (`PATCH /v1/referrals/programs/{id}`), a reward rule
(`PATCH /v1/referrals/rewards/{id}`), the fraud settings
(`PATCH /v1/referrals/programs/{id}/risk-policy`), a level or a milestone bonus; the
dashboard's [**Settings**, **Timing**](https://boltclaw.ai/dashboard/referrals?open=timing)
section shows all of them together. A blank setting uses its default. Each takes effect
from the next conversion; what was already earned keeps its dates.

| Setting | Where | Default | Range | What it guards against | For an in-app invite-a-friend program on a subscription |
|---|---|---|---|---|---|
| `cookie_days` | Program | 30 days | 1 to 365 | How long after a click on a promoter's link a signup or sale is still credited to them. | **30.** The panel's link carries the code into the signup itself; the cookie matters only for a friend who leaves and comes back, and a month covers that. |
| `late_code_days` | Program | 14 days | 0 to 365 | A code typed on a signup more than this many days after Bolt Claw first saw the customer is refused (`late_code`): counted from that first sighting to when the event arrives, never from `occurred_at`. | **1.** An in-app "Enter a referral code" field sits next to the signup; a day covers somebody who finds their friend's code the next morning, and an old account cannot claim one later. |
| `new_customer_hours` | Program | Unset: any age (72 hours on a program made from a template) | 1 to 8,760 | An account older than this cannot be attributed to a promoter: the event's `occurred_at` minus `customer.created_at` (else Bolt Claw's first sighting of the customer). A customer already attributed keeps earning their promoter. | **24.** Send the signup when the account is made, with `customer.created_at` from your own user record: a friend who signs up through the link is minutes old. A day leaves room for a signup you send after an email is confirmed. Never send the account's creation time as `occurred_at`: every account would look new. |
| `new_customer_scope` | Program | `leads` (`all` on Refer a friend and a waitlist made from a template) | `leads` or `all` | Which events the window applies to: signups only, or every event (a code typed at an existing free user's first payment is refused too). | **all.** In an invite-a-friend program a new customer is a new account. A friend attributed at their signup still earns their inviter on every later payment, because the window gates only new attributions. |
| `code_window` | Program | `account_age`: the new-customer and late code windows above | `account_age` or `first_payment` | `first_payment`: a code is taken until the customer's first paid sale, within `code_window_days` of the account, for the entries in `code_window_entries`; after a paid sale it is refused (`paid_before`), and the late code window does not also apply. | **first_payment.** Inside an AI assistant the account is made at the connect step, before a friend can type anything; a friend who hears of the code two days later should still be welcomed, and nobody who already paid can attach one. Send `customer.first_paid_at` when the program records no sales of its own. |
| `code_window_days` | Program | 30 days (used only with `code_window: first_payment`) | 1 to 365 | Under a first-payment window, an account older than this many days cannot attach a code even before paying (`customer_too_old`): from `customer.created_at`, else from when Bolt Claw first saw the customer. | **30.** A month covers a friend who connects first and hears of the code later; set `code_window_entries` to typed codes only, so a link keeps its new-customer window as before. |
| `hold_days` | Program | 30 days | 0 to 365 | How long a commission or reward waits before it is approved (or ready to give), so a refund or dispute can still cancel it. | **30.** A monthly plan's refunds come in its first month; the inviter's reward waits that out. |
| `hold_days` | Reward rule | Unset: the program's hold | 0 to 365 | One reward rule's own wait instead of the program's, so the friend's reward and the inviter's can wait differently. Risk holds still add on top. | **7 on the friend's reward.** Long enough to see most refunds of a first payment, short enough that the friend has their free month before the next monthly invoice. After a reward is given a refund no longer takes it back, so the inviter's keeps the program's 30. |
| `promoter_cap_window` | Reward rule | `lifetime` (when the rule has a limit) | `lifetime`, `calendar_year` or `rolling` | The window a reward rule's limit per inviter counts over: all time, the calendar year (UTC), or the last `promoter_cap_days` days before each reward. | **rolling, 365 days.** "At most 12 free months a year per inviter" that does not reset on 1 January for somebody who invited twelve friends in December. |
| `promoter_cap_days` | Reward rule | Unset (only a `rolling` window has one) | 1 to 3,650 | With a `rolling` window: how many days before each reward the limit per inviter counts. | **365.** A year, counted back from each reward. |
| `lead_grant_daily_cap` | Program | 100 | 0 to 100,000 | The most rewards that signups alone may earn in a day (UTC) across the program: a flood of fake signups stops there. | **100.** Raise it only when real signups through invites pass it; most invite-a-friend programs reward the payment, not the signup. |
| `grant_expiry_days` | Program | Unset: never | 1 to 3,650 | How long a reward that is not cash may wait to be given once it is ready, before it lapses and frees its place in a limit. | **Unset.** A free month that waits for the inviter's own subscription should not lapse unless your program terms say it does; state the period there first. |
| `person_cap` | Program | Unset: no limit | 1 to 1,000 | The most rewards one person receives in the program as an inviter and as a friend together, matched by your own id for them on both sides (a free period by default). | **12, with a rolling 365 days.** A person who invites and is invited under two names still stops at one line, counted the same way on both sides. |
| `person_cap_days` | Program | Unset: all time (only with a limit per person) | 1 to 3,650 | With a limit per person: how many days before each reward it counts. | **365.** A year, counted back from each reward, so the limit does not reset on a calendar date. |
| `ask_snooze_days` | Program | 30 days | 1 to 365 | How long "Not right now" in the panel lasts before a person is asked to invite friends again. | **30.** Once a month is reminder enough; asking more often reads as pressure. |
| `extra_hold_days` | Fraud settings | 14 days (the platform's) | 0 to 365 | How much longer a conversion whose risk score reached the hold line waits, on top of the hold. | **14.** It only reaches conversions the score already finds odd; keep the platform's. |
| `new_partner_days` | Fraud settings | 90 days (the platform's) | 0 to 3,650 | How many days after approval a promoter counts as new: it adds 10 to each of their scores and, with Hold new partners longer, makes their earnings wait. | **30.** Your inviters are your own signed-in users, not strangers who applied; a month is enough to see an account behave. |
| `new_partner_hold_days` | Fraud settings | Unset: the extra days held (14) | 0 to 365 | How much longer a new promoter's earnings wait when nothing else holds them; the larger of the two when the score holds them too. | **0.** The hold already covers refunds, and "new" still adds to the score, so a new inviter with another reason to look at is still held. |
| `min_seconds_lead` | Fraud settings | 5 seconds (the platform's) | 0 to 3,600 | A signup sooner than this after its click scores as automated. | **5.** Nobody fills in a signup form in under five seconds. |
| `min_seconds_sale` | Fraud settings | 15 seconds (the platform's) | 0 to 3,600 | A sale sooner than this after its click scores as automated. | **15.** A friend's first payment comes after a signup, so it is never this quick. |
| `min_seconds_shop` | Fraud settings | 30 seconds (the platform's) | 0 to 3,600 | The same for a shop program's order. | **30.** Applies to shop programs only; leave it. |
| `typed_spread_hours` | Fraud settings | 24 hours (the platform's) | 1 to 168 | One code reaching the program's number of new customers (10 by default) with no click within these hours holds their earnings for a person: a code posted where strangers find it. | **24.** A code shared with friends is typed a few times a week; a posted one, dozens of times a day. |
| `window_days` | Level | Unset: all time | 30 to 365 | The days a level's minimum (sales, customers or revenue) counts over, net of refunds. | **Not needed.** Levels suit partner programs; an invite-a-friend program rewards each friend. |
| `window` | Milestone bonus | `lifetime` | `lifetime` or `calendar_month` | Whether a milestone bonus is paid once ever or once each calendar month (UTC); a refund under the line while it is on hold takes it back. | **lifetime.** "A bonus at five friends" is paid once. |
| Payouts after payout details change | Bolt Claw (fixed) | 48 hours | Fixed | A promoter's payouts wait this long after their payout details change, so somebody who took over their account cannot send the money elsewhere before the owner hears. | **Fixed.** The same for every program: the owner's email with "Lock my payouts" needs the time. |
| Clicks from one address | Bolt Claw (fixed) | 60 a minute | Fixed | Past this many clicks from one address in a minute, across Bolt Claw, no more are recorded (the redirect still answers), so a click flood cannot buy a promoter a place. | **Fixed.** The same for every program: a person never clicks this fast. |

## What a short hold risks

A reward rule's own `hold_days` lets the friend's reward and the inviter's wait
differently. A refund or dispute cancels what is still on hold; after a reward is given, a
refund marks it `reversed` and nothing is taken back. So a short hold gives sooner and
risks more: seven days on the friend's free month sees most refunds of a first payment
and still arrives before the next monthly invoice, while the inviter's reward keeps the
program's 30. The risk score's extra days add on top of any rule's hold.

To hear when a reward that was given is refunded or disputed (`reversed_after_reward`), or
when a flag waits for you, switch those on in [owner notifications](https://boltclaw.ai/docs/referral-notifications).

## The same periods in staging and live

Every period on this page, and every switch beside it, is in the program's configuration document
(`GET /v1/referrals/programs/{id}/config`): the program's `hold_days`, `cookie_days`,
`late_code_days`, `new_customer_hours`, `grant_expiry_days` and `person_cap_days`, each rule's
`hold_days` and `promoter_cap_days`, and the fraud settings' `hold_new_partners`,
`new_partner_days` and `new_partner_hold_days` (only what you set: the rest are the platform's).
A staging program on Stripe's test mode (a program holds one Stripe key, live or test) should
match the live one in all of them; keep the document in your repository, apply it to both with a
dry run first, and `GET .../config/diff?with={other_id}` names any field that drifted, by path:
two programs whose new-partner hold differed for 14 days would have shown
`risk_policy.hold_new_partners` from the first day. [Testing](https://boltclaw.ai/docs/testing#a-second-program-for-staging)
has a worked example.

<!-- https://boltclaw.ai/docs/referral-safeguards as markdown. Generated from openapi.yaml; API version 1.53.0. -->
<!-- Every /docs page answers as markdown: add .md to its path, or send Accept: text/markdown. -->
