# Moving from another referral tool

Keep partners' old links working, bring the partners over, and point your webhooks at the new events.

Moving a referral or affiliate program from Rewardful, FirstPromoter, Tolt or Dub
should not break a single link a partner has already shared. The version 2 tag
reads those tools' link parameters, your billing system connects the same way,
and partners come over through the API today.

## 1. Keep every link that is already out there

Partners' old links put their code in the address under the old tool's
parameter: `?via=` (Rewardful, Dub), `?fpr=` (FirstPromoter), `?ref=` (Tolt), and
others. Tell the tag to read them as well as its own:

```html
<script src="https://boltclaw.ai/referrals/v2.js" defer
        data-accept-params="via,ref,fpr,lmref,tolt_referral"></script>
```

It accepts `ref`, `via`, `fpr`, `lmref` and `tolt_referral`, and its own
`data-param` always counts. A code read this way is kept exactly as one from a
Bolt Claw link, so it reaches your checkout the same way.

**The codes have to exist here too.** An old link credits a partner only when
their Bolt Claw link has the same code. A Bolt Claw code is 3 to 40 lowercase
letters, digits and hyphens; give each partner theirs when you bring them over
(below). A code the old tool allowed with capitals or underscores cannot be
carried as it is: those partners share their new link instead.

## 2. Bring the partners over

- **Your own users with a link** (a refer-a-friend program inside your product):
  create each one with [`POST /v1/referrals/programs/{id}/referrers`](https://boltclaw.ai/docs/api/referrals),
  by your own id for the user, with `code` set to their old code. Running it
  twice updates rather than duplicates.
- **Affiliates** (people outside your product, with their own Bolt Claw account):
  send them the program's join link, or invite them from the dashboard. Each
  chooses their link code when they join, and can set it to their old one.
- A spreadsheet import for partners is coming; until then, the API above is the
  bulk path.

Past commissions are not imported: pay out what the old tool owes, then start
the new program's history from the switch-over date.

## 3. Connect your billing system

Connect the same billing system the old tool read, from the program's Setup
tab: Stripe in one click with the Bolt Claw Stripe App, or any of eleven others
by pasting one secret (see [Connect your billing system](https://boltclaw.ai/docs/referral-setup)).
Keep passing the referral at checkout in the field Bolt Claw reads,
`boltclaw_ref` (or `client_reference_id` on Stripe), rather than the old tool's.

**Switch the old tool's tracking off on the same day**, or both will credit the
same sale.

## 4. Point your webhooks at the new events

If your systems listened to the old tool's webhooks, register an endpoint under
**Settings, Developers, Webhooks** and map the events:

| What happened | Bolt Claw event |
|---|---|
| A partner applied, or was approved | `referral.partner.applied`, `referral.partner.approved` |
| A referred signup or sale was recorded | `referral.conversion.created` |
| A commission was earned, or taken back by a refund | `referral.commission.created`, `referral.commission.reversed` |
| A milestone bonus was earned | `referral.bonus.created` |
| A payout was marked paid | `referral.payout.paid` |
| A reward that is not cash is ready to give | `referral.grant.ready` |

Bolt Claw's events carry identifiers only; fetch the details with a key, as
[Webhooks](https://boltclaw.ai/docs/webhooks) explains.

## 5. Check it, then go

The program's setup status shows each part turning green as it arrives: the
tag, billing, signups, sales and codes. Press **Send a test sale** to see the
whole path with test data before you switch the old tool off.

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