# Authentication
Source: https://docs.getreditus.com/affiliate-program-api/authentication

Affiliate Program API - Authentication

All API endpoints require authentication via Bearer tokens, which can be obtained from the App Settings, provided your plan includes API access.


# Introduction
Source: https://docs.getreditus.com/affiliate-program-api/introduction

This is the public API documentation for Reditus Affiliate Programs

All our API calls use JSON format.

## Allowed HTTPs requests

<pre>
  PUT     : To create resource
  POST    : Update resource
  GET     : Get a resource or list of resources
  DELETE  : To delete resource
</pre>

## Server Responses

* 200 `OK` - the request was successful (some API calls may return 201 instead).
* 201 `Created` - the request was successful and a resource was created.
* 204 `No Content` - the request was successful but there is no representation to return (i.e. the response is empty).
* 400 `Bad Request` - the request could not be understood or was missing required parameters.
* 401 `Unauthorized` - authentication failed or user doesn't have permissions for requested operation.
* 403 `Forbidden` - access denied.
* 404 `Not Found` - resource was not found.
* 405 `Method Not Allowed` - requested method is not supported for resource.


# Rate Limits
Source: https://docs.getreditus.com/affiliate-program-api/rate-limits

Affiliate Program API Rate Limits

All endpoints are subject to a rate limit of **100 requests** every **5 minutes**.


# List Commissions
Source: https://docs.getreditus.com/affiliate-program-api/v1/commissions/index

GET /v1/commissions
Retrieve a paginated list of commissions



# Show Commission
Source: https://docs.getreditus.com/affiliate-program-api/v1/commissions/show

GET /v1/commissions/{id}
Show data for a commission.



# List affiliates
Source: https://docs.getreditus.com/affiliate-program-api/v1/partners/index

GET /v1/partners
Retrieve a paginated list of partners.



# Show affiliate
Source: https://docs.getreditus.com/affiliate-program-api/v1/partners/show

GET /v1/partners/{id}
Show data for a partner



# List Partnerships
Source: https://docs.getreditus.com/affiliate-program-api/v1/partnerships/index

GET /v1/partnerships
Retrieve a paginated list of partnerships.



# Show Partnership
Source: https://docs.getreditus.com/affiliate-program-api/v1/partnerships/show

GET /v1/partnerships/{id}
Show data for a partnership.



# Create Payment
Source: https://docs.getreditus.com/affiliate-program-api/v1/payments/create

POST /v1/payments
The payments API allows you to add payments for your referrals/leads. If you want to track a one-off payment, just don't specify `subscription_id`, `interval` and `interval_count`.



# Show Payment
Source: https://docs.getreditus.com/affiliate-program-api/v1/payments/show

GET /v1/payments/{id}
Show data for a payment.



# Churn Referral
Source: https://docs.getreditus.com/affiliate-program-api/v1/referrals/churn

POST /v1/referrals/churn
Marks a referral as churned, so it no longer counts as an active paying referral. Use this when a referral cancels their subscription. Identify the referral by your own `referral_uid`, the referral's `referral_email`, or the Reditus `referral_id` - the same identifiers you use when creating a payment. If the referral pays again afterwards, sending a new payment automatically reactivates it, so no history is lost.



# List Referrals
Source: https://docs.getreditus.com/affiliate-program-api/v1/referrals/index

GET /v1/referrals
Retrieve a paginated list of referrals



# Show Referral
Source: https://docs.getreditus.com/affiliate-program-api/v1/referrals/show

GET /v1/referrals/{id}
Show data for a referral.



# Create Refund
Source: https://docs.getreditus.com/affiliate-program-api/v1/refunds/create

POST /v1/refunds
Marks a commission as rejected based on a refunded payment. Requires a valid `payment_id`.



# Delete Subscription (Deprecating)
Source: https://docs.getreditus.com/affiliate-program-api/v1/subscriptions/destroy

DELETE /v1/subscriptions/{id}
Cancels a subscription.



# Show Subscription (Deprecating)
Source: https://docs.getreditus.com/affiliate-program-api/v1/subscriptions/show

GET /v1/subscriptions/{id}
Show data for a subscription



# Track Conversion (Deprecating) - Use V2 Instead
Source: https://docs.getreditus.com/affiliate-program-api/v1/tracking/conversion

POST /v1/tracking/conversion
The tracking API allows you to track conversions for any affiliate.



# Track Conversion
Source: https://docs.getreditus.com/affiliate-program-api/v2/tracking/conversion

POST /v2/tracking/conversion
The tracking API allows you to track conversions for any affiliate.



# Get Started
Source: https://docs.getreditus.com/affiliate-program/get_started

Get Started with the Reditus affiliate program

| Step                                             | Description                                                                  |
| ------------------------------------------------ | ---------------------------------------------------------------------------- |
| <b>Tracking Script</b>                           | Check guide [here](/affiliate-program/tracking-script/introduction)          |
| <b>Signup Snippet</b>                            | Check guide [here](/affiliate-program/signup-snippet/introduction)           |
| <b>Connect Stripe</b>                            | Connect Stripe [here](https://app.getreditus.com/saas/settings/installation) |
| <b>Configure your Affiliate Program Settings</b> | Config [page](https://app.getreditus.com/saas/affiliate_program/details)     |
|                                                  |                                                                              |


# Advanced Installation
Source: https://docs.getreditus.com/affiliate-program/signup-snippet/advanced_installation

Signup Snippet Advanced Installation

# Advanced Integration (Stripe or API only)

To enhance tracking accuracy, we recommend including an additional parameter in the email. Since email addresses can change over time, having a stable identifier ensures consistency.

## Stripe Integration

### Stripe Customer ID

You can use the Stripe Customer ID you receive from the `customer.created` Stripe event, and use it in the Reditus snippet.

```
window.gr("track", "conversion", { email: "actual@email.com", uid: "cus_123456" }); // Use the actual Stripe Customer ID
```

### Internal User ID

Similarly, you can use your own internal ID of the user. After a user signs up on your platform, trigger the `customer.created` Stripe event and include the `user_id` in the metadata—ideally right after the signup snippet.

```
{
  "id": "evt_1Example1234567890",
  "object": "event",
  "api_version": "2023-10-16",
  "created": 1707859200,
  "data": {
    "object": {
      "id": "cus_1234567890abcdef",
      "object": "customer",
      "metadata": {
          "user_id": "your-internal-customer-id" // Matching is done against this field
      },
    }
  },
  "type": "customer.created"
}
```

**Important:** If the signup snippet runs after the customer.created Stripe event, it must happen within **30 seconds** to ensure the Stripe customer is correctly matched with the referral.

```
window.gr("track", "conversion", { email: "actual@email.com", uid: "your-internal-user-customer-id" });
```

## API Integration

If you’re using the API, ensure you're on **V2 of the Tracking API** and include the `uid` parameter.


# Installation
Source: https://docs.getreditus.com/affiliate-program/signup-snippet/installation

Signup Snippet Installation

## How to install?

**Before installing the snippet, ensure that you have already added the tracking script to your page.**

The `gr` function is only available if you already installed the Tracking Script.

## Video

<iframe title="YouTube video player" />

## React JS

In a React application, you'll need to call the Reditus conversion event in the callback of your sign-up success handler.

```
handleSignupSubmit(values) {
  const { signUp } = this.props;
  signUp({ ...values })
    .then(() => {
      console.log('Account created successfully.');
      if (typeof window.gr === 'function') {
        console.log('✅ gr function is defined');
        window.gr("track", "conversion", { email: "actual@email.com" });
      } else {
        console.log('⛔️ gr function is NOT defined');
      }
    })
    .catch((err) => {
      console.log('Something went wrong. Please try again later!');
    });
}
```

## Javascript

For standard JavaScript, simply include the snippet in your success handler when the user signs up:

```
if (typeof window.gr === 'function') {
window.gr("track", "conversion", { email: "actual@email.com" });
} else {
console.error('Tracking Script not running, check why.');
}
```

## Ruby On Rails

If you're using Ruby on Rails, you'll need to mark new referrals when a user successfully signs up. Add the following code to your application to track user registrations using the **Devise** gem.

1. **Controller**: In your `app/controllers/users/registrations_controller.rb`, you’ll track successful user sign-ups like this:

```
class RegistrationsController < Devise::RegistrationsController
  def create
    #...
    resource.save
    if resource.persisted?
      # Account created
      session[:reditus_referral] = sign_up_params[:email]
    else
      # Authentication failed
      # ...
    end
  end
end
```

Here, we store the email of the newly created user in session\[:reditus\_referral].

2. **View**: In your `app/views/layouts/application.html.erb`, add the following code to call the tracking method after the registration is complete:

```
<% if session[:reditus_referral].present? %>
  <script>
    window.gr("track", "conversion", { email: "<%= session[:reditus_referral] %>" });
  </script>
<% end %>
```


# Introduction
Source: https://docs.getreditus.com/affiliate-program/signup-snippet/introduction

Signup Snippet Introduction

# What is the Signup Snippet?

The Reditus Sign-up Snippet is a single line of JS code that should be triggered after a successful sign-up.

This snippet sends Reditus the email (or uid) of the person who signed up, ideally right after registration or when onboarding flow started.

```
  gr('track', 'conversion', { email: "email@example.com", uid: "1234-abcd });
```

**Make sure to replace the email and uid with the actual user data.**

## How to install?

**Before installing the snippet, ensure that you have already added the tracking script to your page.**

The `gr` function is only available if you already installed the Tracking Script.


# Excluding plans & prices
Source: https://docs.getreditus.com/affiliate-program/stripe/excluding_plans

Exclude certain plans from generating commissions

<Info>
  This is a Stripe only feature
</Info>

If you want to exclude a certain plan from generating commissions, you can do that.

1. Go to Stripe -> Product catalogue -> Select the plan you want to exclude (i.e. "Growth plan")
2. Select the price you want to exclude.
3. From the price page, go to "Edit metadata".
4. Add the key "commissions\_disabled", and for the value add "yes" (without the actual `""`).

<img alt="tag3" />

<Info>
  If you want to exclude all the prices in a plan, You can now add the metadata on Product level.
</Info>


# FAQs
Source: https://docs.getreditus.com/affiliate-program/tracking-script/faq

Frequently asked questions

## We installed our script, but it isn’t working properly. What could be wrong?

* It’s not installed on all pages (including the sign-up page).
* You've installed the script twice on the same page.
* You’ve used the wrong GTM container.
* You haven’t added it before the `</head>` tag.

## We can't verify the tracking script on the installation page

If the tracking script is installed, but you can't have it go to **'verified'** on the installation page, you probably are not using an affiliate link to test it. Make sure to use the link provided in your installation page to test the tracking, this replicates an affiliate link.

<img alt="tracking-script1" />

If this doesn't work, see if the cookie is being placed by checking the developer console in your chrome browser. The cookie `gr_id` should be present when going to the website using the link from your installation page.

If the cookie isn't present; check your installation of the tracking script.

<img alt="tracking-script2" />

If the cookie is present; contact us so we can investigate further for you.

## I have a composit TLD, 2td - second level domain.

We have second level domain and the tracking script isn't working? This could be we have not added this on our backend, as these work a bit different than normal domains. Ping us in chat and we will get this sorted for you.


# Installation
Source: https://docs.getreditus.com/affiliate-program/tracking-script/installation

Tracking Script Installation

# How to install the tracking script?

## Video

<iframe title="YouTube video player" />

## Ading the Tracking Script to an HTML Website

To ensure proper tracking, add the script (which you can find in your Reditus settings) before the closing `</head>` tag of your HTML. This ensures the script is available on all pages, including the crucial referral landing and sign-up pages (e.g., *app.getreditus.com*).

**The script must be added on all pages and subdomains.**

## Adding the Tracking Script to Google Tag Manager

Watch our tutorial on how to add the script via Google Tag Manager: [Loom Tutorial](https://www.loom.com/share/836ca0ff14904cba885387794685a153?sid=3fb8dd6b-de0e-420c-9662-cbda52e99d4c)

Steps:

1. Log into your [Tag Manager Account](https://tagmanager.google.com/).
2. Create a new Tag.
   <img alt="tag1" />
3. Set up the tag like the image below and hit Save.
   <img alt="tag2" />
4. Submit your changes via the dashboard.
   <img alt="tag3" />

## Adding the Reditus Tracking Script to a WordPress Website

1. Log in to your WordPress admin panel.
2. Install a Header & Footer Script plugin (if you haven’t already).
3. Navigate to Settings > Header and Footer Scripts.
4. Paste the tracking script into the Header box.
   <img alt="wp1" />

**In this case, you must add the tracking script before the closing \</head> tag.**


# Introduction
Source: https://docs.getreditus.com/affiliate-program/tracking-script/introduction

Tracking Script Introduction

# What is the tracking script?

The tracking script is essential for monitoring affiliate conversions on your website. It tracks when someone clicks an affiliate link and completes a sign-up. After an affiliate link is clicked, a cookie 🍪 is placed on the user's device. You control the duration of this cookie in your dashboard.

## How to install?

**The script must be added on all pages and subdomains.**

## Script structure

Do **not** use this script directly. Use the one you have in your [dashboard](https://app.getreditus.com/saas/settings/installation).

```
  <script>
  (function (w, d, s, p, t) {
    w.gr = w.gr || function () {
      w.gr.ce = 60; w.gr.q = w.gr.q || []; w.gr.q.push(arguments);
    };
    p = d.getElementsByTagName(s)[0];
    t = d.createElement(s); t.async = true; t.src = "https://script.getreditus.net/v2.js"; p.parentNode.insertBefore(t, p); })(window, document, "script");
    gr("initCustomer", "YOUR-REDITUS-UID");
    gr("track", "pageview");
  </script>
```

## Additional notes

Do not place the tracking script behind a cookie consent banner. Since we don’t build visitor profiles, no cookie consent is required.


# Authentication
Source: https://docs.getreditus.com/affiliates-api/authentication

Affiliates API - Authentication

Affiliates API endpoints require authentication via Bearer tokens, which can be obtained from your Affiliate Dashboard in App settings.


# Introduction
Source: https://docs.getreditus.com/affiliates-api/introduction

This is the public API documentation for Reditus Affiliates

All our API calls use JSON format.

## Allowed HTTPs requests

<pre>
  PUT     : To create resource
  POST    : Update resource
  GET     : Get a resource or list of resources
  DELETE  : To delete resource
</pre>

## Server Responses

* 200 `OK` - the request was successful (some API calls may return 201 instead).
* 201 `Created` - the request was successful and a resource was created.
* 204 `No Content` - the request was successful but there is no representation to return (i.e. the response is empty).
* 400 `Bad Request` - the request could not be understood or was missing required parameters.
* 401 `Unauthorized` - authentication failed or user doesn't have permissions for requested operation.
* 403 `Forbidden` - access denied.
* 404 `Not Found` - resource was not found.
* 405 `Method Not Allowed` - requested method is not supported for resource.


# Rate Limits
Source: https://docs.getreditus.com/affiliates-api/rate-limits

Affiliates API Rate Limits

All endpoints are subject to a rate limit of **100 requests** every **5 minutes**.


# List Commissions
Source: https://docs.getreditus.com/affiliates-api/v1/affiliate_commissions/index

GET /v1/affiliate/commissions
Retrieve a paginated list of commissions. This is an endpoint from the Affiliates API. You will need an affiliate account and its token in order to use this endpoint.



# List Referrals
Source: https://docs.getreditus.com/affiliates-api/v1/affiliate_referrals/index

GET /v1/affiliate/referrals
Retrieve a paginated list of referrals. This is an endpoint from the Affiliates API. You will need an affiliate account and its token in order to use this endpoint.



# List Sub IDs
Source: https://docs.getreditus.com/affiliates-api/v1/affiliate_sub_ids/index

GET /v1/affiliate/sub_ids
Retrieve a list of Sub IDs. This is an endpoint from the Affiliates API. You will need an affiliate account and its token in order to use this endpoint. Sub IDs are present in the affiliate links via the 'sid' query params.



# Platform overview
Source: https://docs.getreditus.com/get-started/introduction

The resources you need to get started with Reditus

# Get started with the Reditus Platform

The Reditus Platform helps B2B SaaS companies to set up, manage and maximise their affiliate or in-app referral program. With our platform you can set up the tracking, and recruit affiliates outside of your own network, all with the goal of growing your MRR.

See below more general information about the platform. Want to see the API’s directly? Use the toggles at top of the screen.

## How the platform is organized

The Reditus platform is organized into two products:

1. Affiliate Program
2. Referral Program

As they are treated as two separate products, we have created two different sections for them. Good to know; they do use the same tracking mechanisms.

## Affiliate Program

Want to grow by leveraging people outside your own network / userbase? Than the affiliate program is the best fit for you. We will help you to set up an affiliate program, manage & recruiting affiliates, track all payments and handle the payouts towards affiliates.

### Affiliate Program API

The Affiliate Program API has a set of endpoints which can be used to understand the data around your affiliate program.

You can access the different resources including:

* Affiliates (Partners)
* Partnerships
* Referrals
* Payments
* Tracking

You can find the API Docs [here](/affiliate-program-api/introduction).

### Affiliates API

The Affiliates API is a tool to be used by affiliates or publishers, to get a deeper understanding of their partnerships, programatically.

You can access the different resources including:

* Clicks
* Referrals
* Commissions
* Sub IDs

You can find the API Docs [here](/affiliates-api/introduction).

## Referral Program

The In-app Referral Program is a way to automatically generate a referral link for your users, where they can start recommending you from within YOUR app. They don’t need to sign up to our platform, and we would provide you with all the information needed.

It is a great way to create a viral loop within your own app.

### Referral Program API

You can access the different resources including:

* Advocates (users promoting you)
* Leads (These are simply **referrals**. We wanted to have a clear distinction between these and the affiliate program referrals)

You can find the API Docs [here](/referral-program-api/introduction).


# Authentication
Source: https://docs.getreditus.com/referral-program-api/authentication

Referral Program API - Authentication

All API endpoints require authentication via Bearer tokens, which can be obtained from the App Settings, provided your plan includes API access.


# Introduction
Source: https://docs.getreditus.com/referral-program-api/introduction

This is the public API documentation for Reditus Referral Programs

All our API calls use JSON format.

## Allowed HTTPs requests

<pre>
  PUT     : To create resource
  POST    : Update resource
  GET     : Get a resource or list of resources
  DELETE  : To delete resource
</pre>

## Server Responses

* 200 `OK` - the request was successful (some API calls may return 201 instead).
* 201 `Created` - the request was successful and a resource was created.
* 204 `No Content` - the request was successful but there is no representation to return (i.e. the response is empty).
* 400 `Bad Request` - the request could not be understood or was missing required parameters.
* 401 `Unauthorized` - authentication failed or user doesn't have permissions for requested operation.
* 403 `Forbidden` - access denied.
* 404 `Not Found` - resource was not found.
* 405 `Method Not Allowed` - requested method is not supported for resource.


# Rate Limits
Source: https://docs.getreditus.com/referral-program-api/rate-limits

Referral Program API Rate Limits

All endpoints are subject to a rate limit of **100 requests** every **5 minutes**.


# Create Advocate
Source: https://docs.getreditus.com/referral-program-api/v1/advocates/create

POST /v1/advocates
Create an advocate for your referral program



# Set Payment Method
Source: https://docs.getreditus.com/referral-program-api/v1/advocates/create_payment_method

POST /v1/advocates/{advocate_id}/payment_method
Set or update the payment method for an advocate. The advocate can be looked up by their Reditus ID (UUID) or by their uid (your internal user ID). When switching payment types, the previous payment data is automatically cleared. Use this endpoint to store sensitive payment information (IBAN, PayPal) in Reditus instead of your own systems.



# List Advocates
Source: https://docs.getreditus.com/referral-program-api/v1/advocates/index

GET /v1/advocates
Retrieve a paginated list of advocates



# Show Advocate
Source: https://docs.getreditus.com/referral-program-api/v1/advocates/show

GET /v1/advocates/{id}
Retrieve details of a specific advocate by their Reditus ID (UUID) or by their uid (your internal user ID).



# Get Payment Method
Source: https://docs.getreditus.com/referral-program-api/v1/advocates/show_payment_method

GET /v1/advocates/{advocate_id}/payment_method
Retrieve the masked payment method for an advocate. The advocate can be looked up by their Reditus ID (UUID) or by their uid (your internal user ID). Returns anonymized payment details so you can show a "connected" state without exposing sensitive data.



# List Leads
Source: https://docs.getreditus.com/referral-program-api/v1/leads/index

GET /v1/leads
Retrieve a paginated list of leads



# Show Lead
Source: https://docs.getreditus.com/referral-program-api/v1/leads/show

GET /v1/leads/{id}
Show data for a lead.



# Create Payment
Source: https://docs.getreditus.com/referral-program-api/v1/payments/create

POST /v1/payments
The payments API allows you to add payments for your referrals/leads. If you want to track a one-off payment, just don't specify `subscription_id`, `interval` and `interval_count`.



# Create Refund
Source: https://docs.getreditus.com/referral-program-api/v1/refunds/create

POST /v1/refunds
Marks a commission as rejected based on a refunded payment. Requires a valid `payment_id`.



# List Reward Triggers
Source: https://docs.getreditus.com/referral-program-api/v1/reward_triggers/index

GET /v1/reward_triggers
Retrieve a paginated list of reward triggers configured for your referral program. Reward triggers define the conditions and amounts for rewarding advocates.



# List Rewards
Source: https://docs.getreditus.com/referral-program-api/v1/rewards/index

GET /v1/rewards
Retrieve a paginated list of rewards



# Update Reward
Source: https://docs.getreditus.com/referral-program-api/v1/rewards/update

PUT /v1/rewards/{id}
Set the reward's state to 'paid'



# Track Conversion
Source: https://docs.getreditus.com/referral-program-api/v2/tracking/conversion

POST /v2/tracking/conversion
The tracking API allows you to track conversions for any affiliate.



# Authenticating the User
Source: https://docs.getreditus.com/referral-program/authentication

Generate a JSON Web Token (JWT) to securely associate referral data with individual users.

This guide is the second installment in a three-part series on integrating the Reditus Referral Program In-App Widget. In this section, we focus on **generating a JWT** so each user’s referral activity is linked to the correct account. Authentication is handled on your backend to ensure your **product secret** remains private.

## Overview

A JWT is used to identify the user when the widget loads. The **product secret** from Reditus is critical for signing this token and should never be exposed in front-end code. Instead, you will generate the token on your server and pass it to your client.

## Examples

<CodeGroup>
  ```js NodeJS (Express + Jose) theme={null}
  const { SignJWT } = require("jose");

  app.post("/referral-program/generate-token", async (req, res) => {
    const SECRET = "YOUR_PRODUCT_SECRET";
    const PRODUCT_ID = "YOUR_PRODUCT_ID";
    const userId = req.body.userId; // e.g., from request payload

    try {
      const secretKey = new TextEncoder().encode(SECRET);
      const token = await new SignJWT({
        ProductId: PRODUCT_ID,
        UserId: userId,
        iat: Math.floor(Date.now() / 1000),
      })
        .setProtectedHeader({ alg: "HS512", typ: "JWT" })
        .sign(secretKey);

      return res.json({ token });
    } catch (error) {
      return res.status(500).json({ error: "Token generation failed" });
    }
  });
  ```

  ```rb Ruby (Rails + jwt) theme={null}
  # config/routes.rb
  Rails.application.routes.draw do
    post 'referral-program/tokens', to: 'referral_tokens#create'
  end

  # app/controllers/referral_tokens_controller.rb
  require 'jwt'

  class ReferralTokensController < ApplicationController
    def create
      secret     = "YOUR_PRODUCT_SECRET"
      product_id = "YOUR_PRODUCT_ID"
      user_id    = params[:userId]

      payload = {
        ProductId: product_id,
        UserId:    user_id,
        iat:       Time.now.to_i
      }

      token = JWT.encode(payload, secret, 'HS512')
      render json: { token: token }
    end
  end
  ```

  ```py Python (Django + pyjwt) theme={null}
  # urls.py
  from django.urls import path
  from .views import generate_referral_token

  urlpatterns = [
      path('referral-program/generate-token/', generate_referral_token, name='generate-referral-token'),
  ]

  # views.py
  from django.http import JsonResponse
  from django.views.decorators.csrf import csrf_exempt
  import jwt
  import time

  @csrf_exempt
  def generate_referral_token(request):
      if request.method == 'POST':
          SECRET      = "YOUR_PRODUCT_SECRET"
          PRODUCT_ID  = "YOUR_PRODUCT_ID"
          user_id     = request.POST.get('userId') or request.GET.get('userId')

          payload = {
              "ProductId": PRODUCT_ID,
              "UserId":    user_id,
              "iat":       int(time.time())
          }

          token = jwt.encode(payload, SECRET, algorithm='HS512')
          return JsonResponse({"token": token})
      return JsonResponse({"error": "Only POST allowed"}, status=405)
  ```
</CodeGroup>

You can generate JWTs in virtually any language or framework using popular libraries: [jwt.io/libraries](https://jwt.io/libraries)

## Parameters

| Parameter          | Type   | Description                                                                                                      |
| ------------------ | ------ | ---------------------------------------------------------------------------------------------------------------- |
| `SECRET`           | string | **Required.** The product secret obtained from your Reditus dashboard. Must never be exposed on the client side. |
| `PRODUCT_ID`       | string | **Required.** The unique product identifier from the Reditus configuration.                                      |
| `USER_ID`          | string | **Required.** Your internal user identifier (e.g., database ID) that will be tied to referral data.              |
| `tokenPayload`     | object | **Payload** for the JWT. In this example, includes `ProductId`, `UserId`, and `iat`.                             |
| `tokenPayload.iat` | number | The current time in seconds (issued at). Ensures the token creation time is recorded.                            |

## Usage

1. **Generate** this token on your backend using the product secret and product ID.
2. **Send** the token to your frontend (e.g., via an API response).
3. **Use** the token in the auth\_token parameter of the `gr("loadReferralWidget", ...)` (detailed in [Loading the Widget](./loading)).

## Next steps

**Final Step:** Continue to [Showing the Widget Modal](./show) to learn how to present the referral interface to users.


# Get Started
Source: https://docs.getreditus.com/referral-program/get_started

Get Started with the Reditus referral program

| Step                                            | Description                                                                             |
| ----------------------------------------------- | --------------------------------------------------------------------------------------- |
| <b>Tracking Script</b>                          | Check guide [here](/affiliate-program/tracking-script/introduction)                     |
| <b>Signup Snippet</b>                           | Check guide [here](/affiliate-program/signup-snippet/introduction)                      |
| <b>Connect Stripe</b>                           | You can find it [here](https://getreditus.com/saas/settings/installation)               |
| <b>Configure your Referral Program Settings</b> | Referral config [page](https://app.getreditus.net/saas/referral_program/config/details) |
| <b>Adding the widget</b>                        | You can find more details on this [page](/referral-program/loading)                     |
| <b>Double sided benefits (webhooks)</b>         | You can find more details about webhooks on this [page](/webhooks/get_started)          |


# Languages
Source: https://docs.getreditus.com/referral-program/languages

Display the Reditus referral program widget in your user's language.

The in-app referral widget can be displayed in several languages. By default the widget is shown in **English**. You can select a different language per user by passing the `lang` option when you load the widget.

## Supported Languages

| Code | Language          |
| ---- | ----------------- |
| `en` | English (default) |
| `fr` | French            |
| `es` | Spanish           |
| `de` | German            |
| `pt` | Portuguese        |
| `it` | Italian           |
| `pl` | Polish            |
| `nl` | Dutch             |

## Setting the Language

Pass the `lang` option to `gr("loadReferralWidget", ...)` with one of the supported codes:

```javascript Javascript theme={null}
window.gr("loadReferralWidget", {
  product_id: PRODUCT_ID,
  auth_token: authToken,
  lang: "de", // Display the widget in German
  user_details: {
    email: "john@example.com",
    first_name: "John",
    last_name: "Doe",
    company_id: "1as2-3df4-5fg6-7hj8",
    company_name: "Acme",
  },
});
```

Set `lang` to the language your user has selected in your application. If you load the widget again with a different `lang`, the new language takes effect the next time the widget is shown.

## How It Works

* **English is the default.** If you omit `lang`, or pass a value that is not supported, the widget falls back to English.
* **Region variants are accepted.** Values such as `fr-CA` or `pt-BR` are matched to their base language (`fr`, `pt`). If the base language is not supported, the widget falls back to English.
* **English is always available instantly.** English ships with the widget. The other languages are loaded on demand the first time they are needed, so there is no extra cost for users on the default language.
* **Safe fallback.** If a translation cannot be loaded for any reason, the widget continues to work and shows English instead.

## What Gets Translated

The `lang` option translates the widget's own interface: tab names, buttons, labels, instructions, and status messages.

Content that comes from your Reditus configuration is shown as you entered it, and is **not** translated automatically. This includes:

* Your referral program name.
* Custom reward descriptions.
* Your Terms and Conditions.
* Monetary amounts and currencies.

<Note>
  If you need this configured content in another language, set it in the
  language you want your users to see in your Reditus referral program
  settings.
</Note>

## Next steps

Continue to [Authenticating the User](./authentication) to learn how to generate the `auth_token` (JWT), or [Showing the Widget Modal](./show) to display the referral interface.


# Loading the Widget
Source: https://docs.getreditus.com/referral-program/loading

Learn how to load the Reditus referral program widget into your application.

This document is part of a 3-part guide for integrating the Reditus Referral Program In-App Widget. In this first step, we’ll cover how to **load** the widget into your application. Loading the widget is essential because it brings in the necessary JavaScript and exposes the functions you’ll need to display referral information to your users.

## Overview

The Reditus referral widget is loaded via the [**Pageview Tracking Script**](\(https://app.getreditus.com/saas/settings/installation\)), that should already be installed in your app.

You should add the following snippet **where your frontend has access to user data and the JWT token from your backend**. Once you invoke the `gr("loadReferralWidget", ...)` method, it automatically fetches the referral program code and makes the widget available through `window.referralWidget`.

## Example Usage

```javascript Javascript theme={null}
const authToken = await fetchAuthToken();

window.gr("loadReferralWidget", {
  product_id: PRODUCT_ID,
  auth_token: authToken,
  lang: "fr", // Optional. Defaults to English. See "Languages".
  user_details: {
    email: "john@example.com",
    first_name: "John",
    last_name: "Doe",
    company_id: "1as2-3df4-5fg6-7hj8",
    company_name: "Acme",
  },
});
```

## Parameters

| Parameter                   | Type   | Description                                                                                                                                                                                                           |
| --------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `product_id`                | string | **Required.** The Product ID from your Reditus configuration, available at [app.getreditus.com/saas/referral\_program/config/authentication](https://app.getreditus.com/saas/referral_program/config/authentication). |
| `auth_token`                | string | **Required.** A JSON Web Token (JWT) generated on your server using your Reditus **product secret**. Refer to [Authenticating the User](./authentication) for details on token creation.                              |
| `lang`                      | string | **Optional.** The display language for the widget interface. Defaults to `en` (English). Supported values: `en`, `fr`, `es`, `de`, `pt`, `it`, `pl`. See [Languages](./languages) for details.                        |
| `user_details`              | object | **Required to send at least one field within.** Contains user information to associate referral program data with a specific user. (See breakdown of nested fields below.)                                            |
| `user_details.first_name`   | string | The user's first name.                                                                                                                                                                                                |
| `user_details.last_name`    | string | The user's last name.                                                                                                                                                                                                 |
| `user_details.email`        | string | **Required on free plan for sending email notifications towards the advocate.** The user's email address.                                                                                                             |
| `user_details.company_id`   | string | The company ID or organization associated with the user.                                                                                                                                                              |
| `user_details.company_name` | string | The company name or organization associated with the user.                                                                                                                                                            |

Once called, the script fetches the referral widget and attaches it to window\.referralWidget, allowing you to interact with it in your application.

## Next steps

Check out [Authenticating the User](./authentication) to learn how to generate the `auth_token` (JWT).


# Referral Rewards
Source: https://docs.getreditus.com/referral-program/referral_rewards

Give rewards to the users advocates bring in

To get started with webhooks, visit the [Webhooks Getting Started](/webhooks/get_started) page.

For details on the referral event, see the [`lead.created`](/webhooks/referral-program/lead_created) webhook documentation.

Please note: you are responsible for implementing the logic to distribute rewards to your users.


# Showing the Widget Modal
Source: https://docs.getreditus.com/referral-program/show

Display the in-app referral modal so users can share referral links and track referrals directly in your application.

This guide is the final section in a three-part series on integrating the Reditus Referral Program In-App Widget. Now that you’ve **loaded** the widget (Step 1) and **authenticated** your users (Step 2), the final step is to present the referral interface inside your application.

## Overview

Once the widget is **loaded** with `gr("loadReferralWidget", ...)` and a valid `auth_token` (JWT) is provided, the referral interface is accessible via `window.referralWidget`. You can invoke this at any time to display the referral modal.

There are two ways to display the modal:

1. **[Programmatically via JavaScript](#displaying-the-modal-programmatically)** – Manually trigger the modal from a button or custom UI event.
2. **[Automatically via URL Parameters](#displaying-the-modal-via-url-parameters)** – Open the modal based on a query string like `?reditus-show-referral=program`.

Use whichever approach fits your use case best—or both!

## Displaying the Modal Programmatically

```js Javascript theme={null}
window.referralWidget.show();
```

This method instantly shows the in-app referral modal. Link this action to a button in your UI: top navigation, side menu, or a dedicated "Referrals" page, so users can easily access and share their referral link.

### Implementation Example

<CodeGroup>
  ```js React theme={null}
  import React from "react";

  function ReferralButton() {
    const handleShowReferralModal = () => {
      if (window.referralWidget) {
        window.referralWidget.show();
      } else {
        console.error("Referral widget not initialized or unavailable.");
      }
    };

    return <button onClick={handleShowReferralModal}>Share & Earn</button>;
  }

  export default ReferralButton;
  ```

  ```js Vue theme={null}
  <template>
    <button @click="showReferralModal">Share & Earn</button>
  </template>

  <script>
  export default {
    name: "ReferralButton",
    methods: {
      showReferralModal() {
        if (window.referralWidget) {
          window.referralWidget.show();
        } else {
          console.error("Referral widget not initialized or unavailable.");
        }
      },
    },
  };
  </script>
  ```

  ```js Angular theme={null}
  // referral-button.component.ts
  import { Component } from '@angular/core';

  @Component({
    selector: 'app-referral-button',
    template: `<button (click)="showReferralModal()">Share & Earn</button>`
  })
  export class ReferralButtonComponent {
    showReferralModal(): void {
      if ((window as any).referralWidget) {
        (window as any).referralWidget.show();
      } else {
        console.error('Referral widget not initialized or unavailable.');
      }
    }
  }
  ```

  ```js Svelte theme={null}
  <script>
    function showReferralModal() {
      if (window.referralWidget) {
        window.referralWidget.show();
      } else {
        console.error("Referral widget not initialized or unavailable.");
      }
    }
  </script>

  <button on:click={showReferralModal}>Share & Earn</button>
  ```

  ```js Plain Javascript theme={null}
  <button id="showReferralModalBtn">Share & Earn</button>
  <script>
    document.getElementById("showReferralModalBtn").addEventListener("click", function() {
      if (window.referralWidget) {
        window.referralWidget.show();
      } else {
        console.error("Referral widget not initialized or unavailable.");
      }
    });
  </script>
  ```
</CodeGroup>

## Displaying the Modal via URL Parameters

The widget also supports deep linking using a query parameter like:

`?reditus-show-referral=program`

When the URL contains this parameter, the referral widget will **automatically open** and optionally switch to a specific tab:

| Value       | Behavior                           |
| ----------- | ---------------------------------- |
| `program`   | Opens the **Referral Program** tab |
| `referrals` | Opens the **Referrals** tab        |
| `rewards`   | Opens the **Rewards** tab          |

### Example URLs

* `https://your-app.com/dashboard?reditus-show-referral=program`
* `https://your-app.com/account/settings?reditus-show-referral=referrals`
* `https://your-app.com/billing?reditus-show-referral=rewards`

> ℹ️ The modal will open automatically after the widget is loaded and the user is authenticated.


# Excluding plans & prices
Source: https://docs.getreditus.com/referral-program/stripe/excluding_plans

Exclude certain plans from generating rewards

<Info>
  This is a Stripe only feature
</Info>

If you want to exclude a certain plan from generating rewards, you can do that.

1. Go to Stripe -> Product catalogue -> Select the plan you want to exclude (i.e. "Growth plan")
2. Select the price you want to exclude.
3. From the price page, go to "Edit metadata".
4. Add the key "rewards\_disabled", and for the value add "yes" (without the actual `""`).

<img alt="tag3" />

<Info>
  If you want to exclude all the prices in a plan, You can now add the metadata on Product level.
</Info>


# partnership.accepted
Source: https://docs.getreditus.com/webhooks/affiliate-program/partnership_accepted

Partnership - partnership.accepted

## Use Cases

* Sending you a Slack message when a partnership was accepted in Reditus.
* Automatically sending a welcome email to the new affiliate.

### Example payload

```
{
  "event_type": "partnership.accepted",
  "url": "destination-url@example.com",
  "created_at": "2024-05-05",
  "data": {
    "affiliate_name": "Acme",
    "affiliate_email": "john@acme.com",
    "affiliate_first_name": "John",
    "affiliate_last_name": "Doe",
    "accepted_at": "2024-05-05"
  }
}
```


# referral.created
Source: https://docs.getreditus.com/webhooks/affiliate-program/referrals_created

Referrals - referral.created

## Use Cases

* Sending you a Slack message when a referral was created in Reditus.
* Generating a Stripe discount for the end user automatically.

### Example payload

```
{
  "event_type": "referral.created",
  "url": "destination-url@example.com",
  "created_at": "2024-05-05",
  "data": {
    "affiliate_email": "affiliate@example.com",
    "referral_id": "6412-smga-1314-munw",
    "referral_uid": "your-referral-uid", // Your internal ID of the referral
    "referral_email": "john@example.com"
  }
}
```


# Get Started
Source: https://docs.getreditus.com/webhooks/get_started

Send events from Reditus to webhook endpoints

### Description

Integrating our webhooks allows your system to react instantly to key events — like when a new reward is generated — without the need to constantly poll our API. They are secure by design, as each webhook is signed, so you can confidently verify authenticity.

### Security

We send a `X-Signature` Header which contains the signed payload. It is recommended to compare the signed payload with the `X-Signature` we provide to make sure the request comes from us.

### Client side example

<CodeGroup>
  ```ruby Ruby theme={null}
  expected_signature = OpenSSL::HMAC.hexdigest("SHA256", webhook_secret, raw_body)

  if Rack::Utils.secure_compare(expected_signature, request.headers['X-Signature'])
    # Valid
  else
    # Reject
  end
  ```

  ```go Go theme={null}
  import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "net/http"
  )

  func verifySignature(secret, rawBody string, r *http.Request) bool {
    signature := r.Header.Get("X-Signature")
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(rawBody))
    expectedMAC := mac.Sum(nil)
    expectedSignature := hex.EncodeToString(expectedMAC)

    return hmac.Equal([]byte(signature), []byte(expectedSignature))
  }
  ```

  ```python Python theme={null}
  import hmac
  import hashlib

  def verify_signature(secret, raw_body, signature):
      expected_signature = hmac.new(
          key=secret.encode(),
          msg=raw_body.encode(),
          digestmod=hashlib.sha256
      ).hexdigest()
      return hmac.compare_digest(expected_signature, signature)
  ```

  ```javascript Node.js theme={null}
  const crypto = require('crypto');

  function verifySignature(secret, rawBody, req) {
    const signature = req.headers['x-signature'];
    const expectedSignature = crypto
      .createHmac('sha256', secret)
      .update(rawBody, 'utf8')
      .digest('hex');

    return crypto.timingSafeEqual(
      Buffer.from(signature, 'utf8'),
      Buffer.from(expectedSignature, 'utf8')
    );
  }
  ```

  ```csharp .NET theme={null}
  using System.Security.Cryptography;
  using System.Text;

  bool VerifySignature(string secret, string rawBody, string signature)
  {
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(rawBody));
    var expectedSignature = BitConverter.ToString(hash).Replace("-", "").ToLower();

    return CryptographicOperations.FixedTimeEquals(
      Encoding.UTF8.GetBytes(signature),
      Encoding.UTF8.GetBytes(expectedSignature)
    );
  }
  ```

  ```php PHP theme={null}
  function verify_signature($secret, $raw_body, $signature) {
    $expected_signature = hash_hmac('sha256', $raw_body, $secret);
    return hash_equals($expected_signature, $signature);
  }
  ```

  ```java Java theme={null}
  import javax.crypto.Mac;
  import javax.crypto.spec.SecretKeySpec;
  import java.nio.charset.StandardCharsets;

  public boolean verifySignature(String secret, String rawBody, String signature) throws Exception {
    Mac hmac = Mac.getInstance("HmacSHA256");
    SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
    hmac.init(secretKey);
    byte[] hash = hmac.doFinal(rawBody.getBytes(StandardCharsets.UTF_8));

    String expectedSignature = bytesToHex(hash);
    return MessageDigest.isEqual(signature.getBytes(), expectedSignature.getBytes());
  }

  private String bytesToHex(byte[] bytes) {
    StringBuilder sb = new StringBuilder();
    for (byte b : bytes) {
      sb.append(String.format("%02x", b));
    }
    return sb.toString();
  }
  ```
</CodeGroup>

More webhooks to be added, if you have any request, let us know.


# advocate.created
Source: https://docs.getreditus.com/webhooks/referral-program/advocate_created

Advocates - advocate.created

## Use Cases

* Sending you a Slack message when a advocate was created in Reditus.
* Sending an email to the advocate

### Example payload

```
{
  "event_type": "advocate.created",
  "url": "destination-url@example.com",
  "created_at": "2024-05-05",
  "data": {
    "advocate_uid": "your-user-advocate-id", // Your internal ID of the advocate
    "advocate_id": "6412-smga-1314-munw",
    "advocate_slug": "jwe512",
    "advocate_referral_link": "https://acme.com/?refby=jwe512",
    "advocate_first_name": "John",
    "advocate_last_name": "Doe",
    "advocate_email": "john@example.com",
    "advocate_company": "Notion",
    "advocate_company_id": "3124-wasg-cgde-7131"
  }
}
```


# lead.created
Source: https://docs.getreditus.com/webhooks/referral-program/lead_created

Leads - lead.created

## Use Cases

* Sending you a Slack message when a lead was created in Reditus.
* Generating a Stripe discount for the end user automatically.

### Example payload

```
{
  "event_type": "lead.created",
  "url": "destination-url@example.com",
  "created_at": "2024-05-05",
  "data": {
    "advocate_uid": "your-user-advocate-id", // Your internal ID of the advocate
    "lead_id": "6412-smga-1314-munw",
    "lead_uid": "your-lead-uid", // Your internal ID of the lead
    "lead_email": "john@example.com"
  }
}
```


# reward.created
Source: https://docs.getreditus.com/webhooks/referral-program/reward_created

Rewards - reward.created

## Use Cases

* Sending you a Slack message when a reward was generated in Reditus.
* Generating a Stripe discount for the end user automatically.

### Example payload

```
{
  "event_type": "reward.created",
  "url": "destination-url@example.com",
  "created_at": "2024-05-05",
  "data": {
    "amount": 5521 // $55.21,
    "currency": "usd",
    "advocate_uid": "your-user-advocate-id", // Your internal ID of the advocate
    "lead_id": "6412-smga-1314-munw",
    "reward_id": "9182-agja-1891-awia",
    "custom_text": "Awesome Hoodie" // Only present when custom reward triggers are used
  }
}
```