Browse docs

Quickstart

Get Rally tracking referrals in about 15 minutes: create a campaign, add one script to your site, connect Stripe, verify a sale, then pay your affiliates.

8 min readUpdated Oct 15, 2026Works with Stripe
1

Create a campaign

A campaign holds your commission terms. Affiliates join a campaign and earn on the sales they refer.

  1. In the Rally app, open Campaigns and click New campaign.
  2. Enter a name and your website URL. Referral links point to this URL, for example https://yoursite.com/?ref=CODE.
  3. Set the commission: a percentage or a flat amount, once or for a number of recurring months.
  4. Choose first-click or last-click attribution and the cookie duration (30 days by default).
  5. Set the payout currency and the minimum payout.

Affiliates apply on the campaign's signup page. Approve them under Affiliates, or turn on Approve new affiliates automatically. On the Affiliates page you can select several pending applications and approve or reject them at once. Each affiliate has a referral code for their links.

2

Install tracker.js

Copy the script tag from Settings, Tracking in the Rally app. It holds your program ID. Add it to every page of your marketing site and app, just before </head>. It reads ?ref= and ?via= links, records the click, and keeps the referral for your campaign's cookie duration.

index.html
<script src="https://api.refhero.io/tracker.js"        data-program="your-program-id"></script>

Use these two functions on window.Rally to read the referral in your checkout code.

console
window.Rally.getAttribution();// { visitor_id: '…', affiliate_id: '…', program_id: '…' }, or nullwindow.Rally.getCheckoutMetadata();// { refhero_program_id: '…', refhero_affiliate_id: '…', refhero_visitor_id: '…' }, or {}

To confirm the install, open a page of your site with a referral link, such as ?ref=CODE. Settings, Tracking then shows Detected. A page view without a referral link does not count, and a click from the Rally app itself does not count.

The referral cookie is host-only. If your marketing site and app use different hosts, forward the ?ref= or ?via= parameter to the app and let tracker.js record the click there. Check that window.Rally.getAttribution() returns the referral before starting checkout.

3

Connect Stripe

In the Rally app, open Settings, Integrations and click Connect Stripe. Rally credits no sale from a Stripe account that is not connected.

When you create a Checkout Session, copy the referral fields from tracker.js into the session metadata. Rally reads them from the checkout.session.completed event. After that it follows the subscription: renewals pay recurring commissions when the campaign has them, and upgrades, downgrades, refunds and disputes adjust the commission.

// server: create the Checkout Sessionconst session = await stripe.checkout.sessions.create({  mode: 'subscription',  line_items: [{ price: 'price_123', quantity: 1 }],  metadata: req.body.rallyMetadata,  success_url: 'https://yourapp.com/welcome',});

On the client, send window.Rally.getCheckoutMetadata() with the checkout request as rallyMetadata. It returns refhero_program_id, refhero_affiliate_id and refhero_visitor_id.

checkout.js
// client: start checkoutawait fetch('/api/checkout', {  method: 'POST',  headers: { 'Content-Type': 'application/json' },  body: JSON.stringify({ rallyMetadata: window.Rally.getCheckoutMetadata() }),});
4

Verify a sale

Open your site through an affiliate's referral link and check that window.Rally.getAttribution() returns the referral. Complete a checkout, then open Sales in the Rally app. The sale appears with its commission.

5

Approve and pay commissions

New commissions are pending. Approve a sale on its page under Sales, or click Approve page in the Commissions view to approve every pending commission on that page. Deny a sale to give the affiliate no commission.

  1. Open Payouts and click Create payout. Rally groups the approved commissions by affiliate and currency. An affiliate below the campaign's minimum payout waits for the next payout.
  2. Pay each affiliate with PayPal, Wise or your usual method.
  3. Open the payout and click Mark as sent. Rally emails each affiliate.

Server-side conversions

Not using Stripe Checkout? Report each sale from your server. Create a key under Settings, API keys and send it in the X-API-Key header.

terminal
curl -X POST https://api.refhero.io/api/v1/track/conversion \  -H "X-API-Key: $RALLY_API_KEY" \  -H "Content-Type: application/json" \  -d '{"program_id": "your-program-id", "external_id": "inv_1042",       "amount": 99, "currency": "USD", "visitor_id": "<from tracker.js>"}'
program_id
Required. Your campaign ID.
external_id
Required. Your ID for the sale, such as an invoice ID. Rally records each ID once.
amount
Required. The sale amount in major units: 99 means $99.00. Must be more than 0.
currency
Required. A three-letter currency code, such as USD.
visitor_id
The visitor_id from window.Rally.getAttribution(). Send this, affiliate_id or coupon_code.
affiliate_id
Credit this affiliate directly.
coupon_code
Credit the affiliate who owns this coupon code.
type
Optional. initial (the default), recurring, upgrade or downgrade.
customer_email
Optional. Rally refuses the sale when the customer email matches the affiliate email.
customer_id
Optional. Your customer ID.
external_subscription_id
Optional. Your subscription ID.

A new sale answers 201 with a pending commission. The same external_id again answers 409.

response
HTTP/1.1 201 Created{  "conversion_id": "…",  "affiliate_id": "…",  "commission_id": "…",  "amount": 99,  "commission_amount": 19.8,  "status": "pending",  "created_at": "2026-10-15T12:00:00Z"}

Next steps

Map coupon codesUnder Campaigns, Coupons, link a code to an affiliate. When a buyer enters that code as a Stripe Checkout promotion code, Rally credits the affiliate, also without a click. A subscription that you create without Checkout (with the Stripe API, a quote or the dashboard) earns from its first invoice when the code is the only discount on that invoice. If the first invoice is 0 (a trial), the commission starts with the first paid invoice. Name the Stripe promotion code (or a coupon applied without one) the same as the Rally code; case does not matter. Referral metadata from tracker.js wins over the code, and the code wins over the visitor alone. A server-side conversion can send the code as coupon_code.
Set tiers and overridesGive top affiliates a higher rate with commission tiers or a per-affiliate override on the campaign.
Watch failed webhooksSettings, Failed webhooks lists Stripe events Rally could not process. Fix the cause, then retry each one.