Set up tracking

Referalli needs three things from your systems: clicks and visits from your website, signups from your app, and payments from your billing provider. Everything you need to start is on the Settings page. This guide covers what to do in the dashboard. The code your developer adds is described in the developer docs.

1. Add the tracking snippet to your website

In Settings, the Install tracking card shows a one-line script tag with your organization's tracking token already filled in. Ask your developer to add it to your marketing site.

The snippet reads partner links (links with ?via= in the address), remembers the referral, and reports visits.

2. Report signups

When a visitor signs up, Referalli needs to link the new customer to the referral. There are two ways to do this:

• From your server. Your developer sends the customer's ID and the referral to Referalli at signup. The Install tracking card names the call to use. See /docs for details.

• From your auth platform. In the Auth platform card, choose the program under Attribute new signups to program, then select Connect Clerk, Connect Supabase or Connect WorkOS. Referalli shows a webhook address and a secret, once. Add the address in your auth platform as a webhook for new users, and have your developer add Referalli's signup metadata to new users. The card lists each connection with its program.

If you use an auth platform, signups are filed under the auth platform's user ID, but your billing provider pays under its own customer ID. To get commissions on those customers' payments, your developer sets referally_customer_ref to the auth user ID in the Stripe customer (or subscription) metadata. After the first linked event, every later payment, renewal and refund for that customer is credited automatically. The developer docs cover the other billing providers.

3. Connect your billing provider

Commissions are created when your billing provider reports a paid invoice. The Billing connections card supports Stripe, Paddle, Lemon Squeezy, Polar, Chargebee, Shopify and a generic webhook for anything else.

1. Choose the provider

   In Billing connections, choose your provider under Connect a billing provider. The card shows how that provider's payments are matched to referrals: by the referral filed under the provider's customer ID, or, if you attributed the signup under another ID, through referally_customer_ref (in Stripe customer or subscription metadata, Paddle custom_data, Lemon Squeezy checkout[custom] or Polar checkout metadata) or the generic webhook's customerRef / linkedCustomerRef. For Chargebee, also enter a Basic-auth username and Basic-auth password of your choice (together at least 8 characters).

2. Connect

   Select Connect followed by the provider's name, such as Connect Stripe. Referalli shows the webhook address, where to add it in the provider's dashboard, and which events to send.

3. Add the webhook in your provider

   In your billing provider's dashboard, add the address as a webhook endpoint and subscribe to the events listed. For Stripe that's invoice.paid, customer.subscription.created/updated/deleted, customer.created, customer.updated, charge.refunded and charge.dispute.created.

4. Exchange the signing secret

   How the secret works depends on the provider:

   • Stripe, Paddle, Polar and Shopify create the signing secret when you add the endpoint. Copy it from the provider, paste it into Signing secret from …, and select Save signing secret. Until you do, that provider's webhooks are rejected.

   • Lemon Squeezy and Generic webhook: Referalli shows a signing secret, once. Copy it into the provider (for Lemon Squeezy, its "Signing secret" field).

   • Chargebee doesn't sign webhooks. In Chargebee, turn on basic authentication for the webhook with the same username and password you entered.

The connection then appears in the list with its webhook path and status. To change a secret later, or if you didn't paste it straight away, select Set secret next to the connection and paste the provider's secret (for Chargebee, the new username:password).

API keys

Your developer may need an API key to report signups from your server.

1. In the API keys card, choose the key's access under Access for the next key:

   • Full — read and write (server integrations) for anything that sends data to Referalli, such as reporting signups.

   • Read-only — GET requests only (reporting, dashboards) for tools that only read data. A read-only key can't change anything.

2. Select Create API key and give the key a name, such as "production server".

3. Copy the key straight away. It's shown only once.

The key list shows each key's name, prefix, Access (Full or Read-only) and status. To stop a key working, select Revoke next to it. A key's access can't be changed later; create a new key instead.

On-chain conversions

If you reward partners for wallet activity, choose the program under Credit on-chain conversions to program in the On-chain conversions card, then select Connect on-chain indexer. Referalli gives you a webhook address and secret for your indexer, once. The card lists each connection with its program.

Check that it works

Before you go live, you can test the whole flow with made-up data. In Tools, the Sandbox card generates billing history for a program and partner you pick, using the Subscription (renewals), Refund or Churn scenario. Select Generate history, then look at Commissions and Reports.