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 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_idfor the referrer equalscustomer.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 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_referralflag (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). - 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_daysafter Bolt Claw first saw the customer is not applied (referral_refused: "late_code", the friend's 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).
- 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).
- 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).
- 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).
- Test data is never paid. Test conversions and rewards are never payable and never counted (test mode).
- 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.
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_idfor the referrer (live or test) equals the event'scustomer.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).
- What happens. For a customer nobody holds, the referral is dropped: the conversion is
recorded as an unreferred one, with
referral_refusedandattribution_skippedbothself_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_refusedonGET /v1/referrals/programs/{id}/stats(live data, in the window), and the program's Overview, Review queue 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 k3f9andMAYA - K3F9aremaya-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, matchesmaya-k3f9when it is the only code of the program that is the same without its hyphens. Two codes that differ only by hyphens (ab-cdandabcd) 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/referralsreads a pasted link the same way, so you can send the code itself. - What generated codes are made of. Ten characters from
23456789abcdefghjkmnpqrstuvwxyz: no0,o,1,iorl, 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: typedmakes new codes of 6 to 8 characters from the same alphabet (code_length), or withcode_prefix: namethe 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, "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
entryis incode_window_entries(null for every entry) is taken until the customer's first paid sale, withincode_window_daysof 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 withpaid_before; past the days, withcustomer_too_old. Sendcustomer.first_paid_atwhenever the program has no billing connection of its own: without a sale or your record, Bolt Claw cannot know. - Inside this window
late_code_daysdoes 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
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.
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
has a worked example.