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.
Create a campaign
A campaign holds your commission terms. Affiliates join a campaign and earn on the sales they refer.
- In the Rally app, open Campaigns and click New campaign.
- Enter a name and your website URL. Referral links point to this URL, for example
https://yoursite.com/?ref=CODE. - Set the commission: a percentage or a flat amount, once or for a number of recurring months.
- Choose first-click or last-click attribution and the cookie duration (30 days by default).
- 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.
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.
<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.
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.
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',});# server: create the Checkout Sessionsession = stripe.checkout.Session.create( mode="subscription", line_items=[{"price": "price_123", "quantity": 1}], metadata=request.json["rallyMetadata"], success_url="https://yourapp.com/welcome",)# server: create the Checkout Sessionsession = Stripe::Checkout::Session.create( mode: 'subscription', line_items: [{ price: 'price_123', quantity: 1 }], metadata: params[: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.
// client: start checkoutawait fetch('/api/checkout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ rallyMetadata: window.Rally.getCheckoutMetadata() }),});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.
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.
- 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.
- Pay each affiliate with PayPal, Wise or your usual method.
- 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.
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.
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"}