Migration from Tolt

Move an affiliate program from Tolt to Ranla affiliates. Links, checkout hand-off and commissions work much the same way; the names differ. One real difference: commissions come straight from your Stripe invoices, so there is no transactions call to make.

Quick mapping

Tolt	Ranla
API key (`Authorization: Bearer`)	`rnl_…` full-access API key (`Authorization: Bearer`)
`https://api.tolt.com/v1`	`https://api.ranla.ai`
Program	Your affiliate program (one per account)
Group / program commission settings	Campaign — `/affiliate-campaigns`
Partner	Partner — `/affiliates`
Link (`param` + `value`)	Link — `/affiliates/{id}/links`, `token` (the `value`)
Customer (`lead`, `trialing`, `active`, `canceled`)	Referral — `/affiliate-referrals` (`lead`, `trialing`, `active`, `cancelled`, …)
Transaction (`POST /v1/transactions`)	Not needed — the Stripe invoice behind a commission (`stripe_invoice_id`)
Commission (`pending`, `approved`, `rejected`)	Commission — `/affiliate-commissions` (`pending` → `earned` → `paid`, or `reversed`)
Payout	Payout — `/affiliate-payouts`
Promotion code	Per-partner promotion code
`POST /v1/clicks` + `POST /v1/customers`	`POST /affiliate-referrals`

Browser script

Tolt	Ranla
`<script src="https://cdn.tolt.io/tolt.js" data-tolt="…">`	`<script async src="https://app.ranla.ai/t.js?key=stxk_…" data-key="stxk_…">`
Link param (`ref`, `via` or your own)	`?via=` and `?ref=` read by default; add others with `data-ref-params`
`window.tolt_referral`	`stx.referral` (empty string when there is none)
`window.tolt_data` (`partner_id`, `cookie_duration`, …)	`stx.affiliate` — `{ id, name, first_name }`, or `null`
`await window.tolt.signup(identifier)` (email or user id)	`stx.referralSignup(email)` or `stx.identify({ email })` — takes an email

Stripe

Tolt	Ranla
`metadata.tolt_referral` on the Checkout Session or subscription	`metadata.ranla_referral` on the Checkout Session, customer, subscription or invoice
Payment Links: a script you add appends `client_reference_id=window.tolt_referral`	Automatic — the script adds `client_reference_id` to `buy.stripe.com` links
Buy Button / Pricing Table: `client-reference-id` set to `window.tolt_referral`	Same attribute, set to `stx.referral` inside `stx.ready`
—	`client_reference_id: stx.referral` on a Checkout Session you create
—	`metadata.ranla = "false"` excludes a customer, subscription or invoice

Partner fields

Tolt `POST /v1/partners`	Ranla `POST /affiliates`
`first_name`, `last_name`, `email`	same (only `email` is required)
`program_id`, `group_id`	`campaign_id` (id or name)
`company_name`, `country_code`	`company`, `country`
`notify_partner`	`send_invite`
`payout_method: paypal` + `payout_details`	`paypal_email`; partners add Wise or bank details in their portal
Link created separately (`POST /v1/links`)	`token` — the primary link, created with the partner

Commission settings

Tolt	Ranla campaign
Percentage / fixed commission	`commission_type: percent` (`commission_bps`, 3000 = 30%) / `flat` (`commission_flat_cents`)
One-time / recurring, duration in months	`commission_duration: once` / `recurring` with `recurring_months` (`null` = lifetime)
Cookie duration	`cookie_days`
Payout terms (NET-15 / 30 / 60)	`hold_days` (refund window before a commission is earned) plus the program's payout day
Tiered rates by customer count	`tiers: [{ min_paid_customers, commission_bps }]`
Minimum payout threshold	Program minimum payout (dashboard)
Auto payouts	Opt-in in the dashboard, with a cap — runs above it wait for your approval

Webhook events

Tolt	Ranla
`partner.created`	`affiliate.created`
Partner approved	`affiliate.approved`
`referral.created` (a new customer)	`referral.created`
`referral.updated` (customer starts paying)	`referral.converted`
`commission.created`	`commission.created`
`commission.updated` (approved)	`commission.earned`
`commission.updated` (rejected, refunded)	`commission.reversed`
Commission paid	`commission.paid`
Payout events	`payout.created`, `payout.paid`, `payout.failed`

Tolt lists its full set in the dashboard's Event Catalog; match any others there by meaning. Signatures use the SuperSendTX-Signature header — see Webhooks.

Import your partners

Export your partners from Tolt, 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 value of the partner's Tolt link, so ?ref=jane keeps working. Tokens are 2–40 lowercase letters, digits, dashes and underscores: uppercase is lowercased and any other character becomes a dash. A Tolt value like michael_scott imports unchanged, so ?ref=michael_scott keeps working. 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.

If your links use a param other than via or ref, list it on the script tag with data-ref-params.

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","send_invite":false}'

See Affiliates API → Create a partner.

Moving over

Turn on the program in the dashboard and create campaigns that match your commission settings.
Import your partners, keeping each one's link value as their token.
Replace server-side POST /v1/clicks and POST /v1/customers calls with POST /affiliate-referrals (token + email, optionally stripe_customer_id). Drop POST /v1/transactions calls — payments are read from your connected Stripe account.
Swap the script tag and the Stripe metadata key. See the affiliate tracking guide.
Attribute existing customers to their partners from the dashboard so recurring commissions continue.