Migration from Rewardful

Move an affiliate program from Rewardful to Ranla affiliates. Most of the move is a find-and-replace: links still use ?via=, checkout still passes a referral id to Stripe, and commissions still come from your Stripe invoices.

Quick mapping

Rewardful	Ranla
API Secret (HTTP Basic auth, secret as username)	`rnl_…` full-access API key (`Authorization: Bearer`)
`https://api.getrewardful.com/v1`	`https://api.ranla.ai`
Affiliate	Partner — `/affiliates`
Campaign	Campaign — `/affiliate-campaigns`
Affiliate link / `token`	Link — `/affiliates/{id}/links`, `token`
Affiliate coupon	Per-partner promotion code
Referral (`conversion_state`: `visitor`, `lead`, `conversion`)	Referral — `/affiliate-referrals`, `status` `lead` → `active`. Anonymous visitors are counted as clicks, not referrals.
Commission (`state`: `pending`, `due`, `paid`, `voided`)	Commission — `/affiliate-commissions`, `status` `pending` → `earned` → `paid`, or `reversed`
Payout	Payout — `/affiliate-payouts`
Magic Link (SSO)	`POST /affiliates/{id}/login-link`

Browser script

Rewardful	Ranla
Queue snippet + `<script async src="https://r.wdfl.co/rw.js" data-rewardful="…">`	`<script async src="https://app.ranla.ai/t.js?key=stxk_…" data-key="stxk_…">` — no queue snippet needed
`?via=` links	`?via=` links (also `?ref=`) — existing partner links keep working when you keep the tokens
`data-rewardful-params` (extra link params)	`data-ref-params`
`data-domains` (cross-domain tracking)	`data-ref-domains`
`?referral=<id>` (preload a referral)	`?referral=<id>`
`Rewardful.referral`	`stx.referral` (empty string when there is none)
`Rewardful.affiliate` (`false` when none)	`stx.affiliate` — `{ id, name, first_name }`, or `null`
`Rewardful.coupon` (the Stripe coupon object)	`stx.coupon` — `{ id, code, label }`, or `null`
`rewardful('ready', cb)`	`stx.ready(cb)`
`rewardful('convert', { email })`	`stx.referralSignup(email)` or `stx.identify({ email })`
`rewardful('source', token)`	`stx.referralSource(token)`
`<form data-rewardful>` (adds a hidden `referral` input)	Add the input yourself: `<input type="hidden" name="referral" data-stx-referral>`

Stripe

Rewardful	Ranla
`client_reference_id: Rewardful.referral` on the Checkout Session	`client_reference_id: stx.referral`
`metadata.referral` on the customer	`metadata.ranla_referral` on the Checkout Session, customer, subscription or invoice
`metadata.rewardful = "false"` to skip a commission	`metadata.ranla = "false"` on the customer, subscription or invoice
Payment Links: a script you add appends `client_reference_id`	Automatic — the script adds `client_reference_id` to `buy.stripe.com` links

Campaign fields

Rewardful	Ranla campaign
`reward_type: percent` / `amount`	`commission_type: percent` / `flat`
`commission_percent` (e.g. `30.0`)	`commission_bps` (e.g. `3000`)
`commission_amount_cents`	`commission_flat_cents`
`max_commission_period_months`	`recurring_months` (`null` = lifetime) with `commission_duration: recurring`
`max_commissions` = 1	`commission_duration: once`
`days_before_referrals_expire`	`cookie_days`
`days_until_commissions_are_due`	`hold_days`
`minimum_payout_cents`	Program minimum payout (dashboard)
`private`	`visibility: private`
`default`	`is_default` (set with `make_default: true`)

Affiliate fields

Rewardful	Ranla partner
`first_name`, `last_name`, `email`	same
`state` (`active`, `disabled`, `suspicious`)	`status` (`active`, `pending`, `invited`, `suspended`, `rejected`) — `disabled` and `suspicious` map to `suspended`
`campaign.id` (`campaign_id` on create)	`campaign_id` (id or name)
`paypal_email`	`paypal_email`
`wise_email`	Partners add Wise or bank details in their portal
`links[].token`	`links[].token`

Webhook events

Rewardful	Ranla
`affiliate.created`	`affiliate.created`
— (affiliates start `active`)	`affiliate.approved` — a partner became active
`affiliate.updated`	`affiliate.updated`
`referral.created` (a new visitor)	— (clicks are not sent as events)
`referral.lead`	`referral.created`
`referral.converted`	`referral.converted`
`commission.created`	`commission.created`
`commission.updated` (when it becomes due)	`commission.earned`
`commission.voided`	`commission.reversed`
`commission.paid`	`commission.paid`
`payout.created`, `payout.paid`, `payout.failed`	same names

Rewardful's affiliate.confirmed, affiliate_link.*, affiliate_coupon.*, sale.*, payout.due, payout.updated and *.deleted events have no counterpart. Signatures use the SuperSendTX-Signature header — see Webhooks.

Import your partners

Export your affiliates from Rewardful, then import them in the dashboard (Affiliates → Partners → Import CSV) — upload the file or paste it. The columns are:

email,first_name,last_name,campaign,token,paypal_email
[email protected],Jane,Doe,Standard,jane,[email protected]

Only email is required. With a header row, columns can be in any order and extra columns are ignored; without one, the order above is assumed.
campaign is a campaign name or id. Rows without one join the campaign you pick in the import dialog.
token is the partner's existing link token, so their ?via= links keep working. Tokens are 2–40 lowercase letters, digits and dashes: uppercase is lowercased and any other character becomes a dash. A token that is already taken gets a numbered variant (jane2), so check the partners list after the import.
Imported partners start active and get no email unless you turn on the welcome email. Up to 5,000 rows per file; duplicate or invalid emails are skipped and listed.

To import from code instead, call POST /affiliates once per partner. Here a taken token returns 409 rather than a variant, so you know every link survived:

curl -X POST https://api.ranla.ai/affiliates \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","first_name":"Jane","token":"jane","campaign_id":"Standard","send_invite":false}'

See Affiliates API → Create a partner.

Moving over

Turn on the program in the dashboard and create campaigns that match yours.
Import your partners, keeping each one's token.
Swap the script tag and the Stripe metadata key, following the tables above. See the affiliate tracking guide.
Attribute existing customers to their partners from the dashboard so recurring commissions continue.
Pay the last Rewardful payout there, then let new commissions accrue here.