Reditus

https://docs.getreditus.com
Admin
Reditus is a platform for B2B SaaS companies to set up, manage, and grow their affiliate and in-app...
Tokens:19,292
Snippets:182
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Implement Referral Button with Plain JavaScript

Source: https://docs.getreditus.com/referral-program/show

This example demonstrates how to attach an event listener to a button to programmatically show the referral modal using plain JavaScript.

```javascript
<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>
```

--------------------------------

### Track User Conversion with Signup Snippet

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

Use this snippet to send user email or UID to Reditus after a successful sign-up. Ensure the `gr` function is available by having the Tracking Script installed.

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

--------------------------------

### Generate JWT in Ruby (Rails + jwt)

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

This Ruby on Rails example demonstrates JWT generation for the referral program. It includes route configuration and controller logic for creating the token.

```ruby
# 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
```

--------------------------------

### Reward Created Webhook Payload

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

This is an example payload for the reward.created webhook. It contains details about the reward, the advocate, and the lead.

```APIDOC
## Webhook: reward.created

### Description
This webhook is triggered when a new reward is generated.

### Use Cases
* Sending Slack notifications upon reward generation.
* Automatically creating Stripe discounts for users.

### Payload Example
```json
{
  "event_type": "reward.created",
  "url": "destination-url@example.com",
  "created_at": "2024-05-05",
  "data": {
    "amount": 5521, 
    "currency": "usd",
    "advocate_uid": "your-user-advocate-id", 
    "lead_id": "6412-smga-1314-munw",
    "reward_id": "9182-agja-1891-awia",
    "custom_text": "Awesome Hoodie" 
  }
}
```

### Payload Fields
* **event_type** (string) - The type of the event, always "reward.created".
* **url** (string) - The destination URL for the webhook.
* **created_at** (string) - The timestamp when the event was created.
* **data** (object) - Contains the details of the reward.
  * **amount** (integer) - The reward amount in the smallest currency unit (e.g., cents for USD).
  * **currency** (string) - The currency of the reward (e.g., "usd").
  * **advocate_uid** (string) - Your internal ID for the advocate.
  * **lead_id** (string) - The ID of the lead associated with the reward.
  * **reward_id** (string) - The unique identifier for the reward.
  * **custom_text** (string, optional) - Custom text associated with the reward, present only for custom reward triggers.
```

--------------------------------

### Stripe Customer Created Event Structure

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

This is an example of the `customer.created` Stripe event structure. The internal user ID should be included in the `metadata.user_id` field for matching.

```json
{
  "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"
}
```

--------------------------------

### Generate JWT in Python (Django + pyjwt)

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

This Python Django example shows how to generate a JWT. It includes URL configuration and a view function to handle token creation.

```python
# 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)
```

--------------------------------

### List Affiliate Commissions (OpenAPI)

Source: https://docs.getreditus.com/affiliates-api/v1/affiliate_commissions

This OpenAPI specification defines the GET /v1/affiliate/commissions endpoint. It includes parameters for filtering by state, sub ID, and creation/state set dates, as well as pagination controls. Authentication is handled via Bearer token.

```yaml
GET /v1/affiliate/commissions
openapi: 3.1.0
info:
  title: Reditus API - Asd
  description: API specification for listing commissions in Reditus.
  version: 1.0.0
servers:
  - url: https://api.getreditus.com/api
security: []
paths:
  /v1/affiliate/commissions:
    get:
      summary: List Commissions
      description: >-
        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.
      parameters:
        - name: state_eq
          in: query
          schema:
            type: string
            description: Filter by state (pending paid rejected)
        - name: sub_id_eq
          in: query
          schema:
            type: string
            description: Filter by sub ID (referral sub_id)
        - name: created_at_lt
          in: query
          schema:
            type: string
            description: Created before (e.g. "2022-12-24%2012:47:45%20+0200")
        - name: created_at_gt
          in: query
          schema:
            type: string
            description: Created after (e.g. "2021-11-23%2012:47:45%20+0200")
        - name: state_set_at_lt
          in: query
          schema:
            type: string
            description: State set at before (e.g. "2022-12-24%2012:47:45%20+0200")
        - name: state_set_at_gt
          in: query
          schema:
            type: string
            description: State set at before (e.g. "2021-12-24%2012:47:45%20+0200")
        - name: page
          in: query
          schema:
            type: integer
            description: Page number
        - name: per_page
          in: query
          schema:
            type: integer
            maximum: 50
            description: Records to be displayed per page
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommissionListResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    CommissionListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Commission'
        meta:
          type: object
          properties:
            pagination:
              type: object
              properties:
                page:
                  type: integer
                per_page:
                  type: integer
                has_more:
                  type: boolean
    Commission:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        attributes:
          type: object
          properties:
            state:
              type: string
            amount:
              type: integer
              description: Amount in cents (e.g., 1000 = $10.00)
            currency:
              type: string
            sub_id:
              type: string
            state_set_at:
              type: integer
            created_at:
              type: integer
            updated_at:
              type: integer
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

```

--------------------------------

### OpenAPI Specification for Listing Referrals

Source: https://docs.getreditus.com/affiliates-api/v1/affiliate_referrals

This OpenAPI 3.1.0 specification defines the GET /v1/affiliate/referrals endpoint. It includes details on request parameters, response schemas, and authentication methods.

```yaml
GET /v1/affiliate/referrals
openapi: 3.1.0
info:
  title: Reditus API - Referrals
  description: API specification for listing referrals in Reditus.
  version: 1.0.0
servers:
  - url: https://api.getreditus.com/api
security: []
paths:
  /v1/affiliate/referrals:
    get:
      summary: List Referrals
      description: >-
        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.
      parameters:
        - name: state_eq
          in: query
          schema:
            type: string
            description: |- 
              Filter by state (clicked converted paid churned rejected) 
               To get clicks, simply specify use the clicked filter
        - name: sub_id_eq
          in: query
          schema:
            type: string
            description: Filter by sub ID
        - name: created_at_lt
          in: query
          schema:
            type: string
            description: Created before (e.g. "2022-12-24%2012:47:45%20+0200")
        - name: created_at_gt
          in: query
          schema:
            type: string
            description: Created after (e.g. "2021-11-23%2012:47:45%20+0200")
        - name: state_set_at_lt
          in: query
          schema:
            type: string
            description: State set at before (e.g. "2022-12-24%2012:47:45%20+0200")
        - name: state_set_at_gt
          in: query
          schema:
            type: string
            description: State set at before (e.g. "2021-12-24%2012:47:45%20+0200")
        - name: page
          in: query
          schema:
            type: integer
            description: Page number
        - name: per_page
          in: query
          schema:
            type: integer
            maximum: 50
            description: Records to be displayed per page
      responses:
        '200': 
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralListResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    ReferralListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Referral'
        meta:
          type: object
          properties:
            pagination:
              type: object
              properties:
                page:
                  type: integer
                per_page:
                  type: integer
                has_more:
                  type: boolean
    Referral:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        attributes:
          type: object
          properties:
            email:
              type: string
            state:
              type: string
            sub_id:
              type: string
            commission_percentage:
              type: integer
            state_set_at:
              type: integer
            commission_end_date:
              type: integer
            created_at:
              type: integer
            updated_at:
              type: integer
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

```

--------------------------------

### Advocate Created Webhook Payload

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

This is an example payload for the advocate.created webhook. It includes event details and data about the newly created advocate.

```APIDOC
## Webhook: advocate.created

### Description
This webhook is triggered when a new advocate is created.

### Event Type
advocate.created

### Payload Structure
- **event_type** (string) - The type of the event, which is "advocate.created".
- **url** (string) - The destination URL for the webhook.
- **created_at** (string) - The timestamp when the event was created.
- **data** (object) - Contains the details of the created advocate.
  - **advocate_uid** (string) - Your internal ID of the advocate.
  - **advocate_id** (string) - The unique identifier for the advocate.
  - **advocate_slug** (string) - The slug associated with the advocate.
  - **advocate_referral_link** (string) - The referral link for the advocate.
  - **advocate_first_name** (string) - The first name of the advocate.
  - **advocate_last_name** (string) - The last name of the advocate.
  - **advocate_email** (string) - The email address of the advocate.
  - **advocate_company** (string) - The company the advocate is associated with.
  - **advocate_company_id** (string) - The unique identifier for the advocate's company.

### Request Example
```json
{
  "event_type": "advocate.created",
  "url": "destination-url@example.com",
  "created_at": "2024-05-05",
  "data": {
    "advocate_uid": "your-user-advocate-id",
    "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"
  }
}
```
```

--------------------------------

### Referral Created Webhook Payload

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

This is an example of the payload received when the referral.created webhook is triggered. It includes event details and data about the new referral.

```APIDOC
## referral.created Webhook

### Description
This webhook is triggered when a new referral is created.

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

### Payload Example
```json
{
  "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",
    "referral_email": "john@example.com"
  }
}
```

### Data Fields
*   **event_type** (string) - The type of event, which is "referral.created".
*   **url** (string) - The destination URL for the webhook.
*   **created_at** (string) - The timestamp when the event occurred.
*   **data** (object) - Contains details about the referral.
    *   **affiliate_email** (string) - The email address of the affiliate.
    *   **referral_id** (string) - The unique identifier for the referral.
    *   **referral_uid** (string) - Your internal unique identifier for the referral.
    *   **referral_email** (string) - The email address of the referred user.
```

--------------------------------

### Referral Created Event Payload

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

This is an example payload for the referral.created event. It contains details about the affiliate, the referral ID, and the referred user's email.

```json
{
  "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"
  }
}
```

--------------------------------

### Allowed HTTP Methods

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

The Reditus Affiliate Programs API supports the following HTTP methods for resource manipulation: PUT for creation, POST for updates, GET for retrieval, and DELETE for removal.

```APIDOC
## Allowed HTTPs requests

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

--------------------------------

### Verify Webhook Signature in Java

Source: https://docs.getreditus.com/webhooks/get_started

Implement webhook signature verification in Java using `javax.crypto.Mac`. This example calculates the HMAC-SHA256 hash and uses a helper method for secure byte comparison.

```java
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();
}
```

--------------------------------

### Partnership Accepted Webhook Payload

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

This is an example of the payload structure received when a partnership is accepted. It includes event details and data about the new affiliate.

```APIDOC
## partnership.accepted Webhook

### Description
This webhook is triggered when a partnership is 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
```json
{
  "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"
  }
}
```
```

--------------------------------

### Lead Created Event Payload

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

This is an example payload for the lead.created event. It includes details about the event type, destination URL, creation timestamp, and specific data related to the lead and advocate.

```json
{
  "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"
  }
}
```

--------------------------------

### OpenAPI Specification for Listing Sub IDs

Source: https://docs.getreditus.com/affiliates-api/v1/affiliate_sub_ids

This OpenAPI 3.1.0 specification defines the GET /v1/affiliate/sub_ids endpoint. It requires Bearer authentication and returns a list of Sub IDs.

```yaml
GET /v1/affiliate/sub_ids
openapi: 3.1.0
info:
  title: Reditus API - Sub IDs
  description: API specification for getting the Sub IDs
  version: 1.0.0
servers:
  - url: https://api.getreditus.com/api
security: []
paths:
  /v1/affiliate/sub_ids:
    get:
      summary: List Sub IDs
      description: >-
        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.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubIdListResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    SubIdListResponse:
      type: object
      properties:
        sub_ids:
          type: array
          items:
            type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

```

--------------------------------

### Verify Webhook Signature in Node.js

Source: https://docs.getreditus.com/webhooks/get_started

Verify webhook authenticity in Node.js using the `crypto` module. This example calculates the HMAC-SHA256 hash and uses `timingSafeEqual` for secure comparison against the `x-signature` header.

```javascript
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')
  );
}
```

--------------------------------

### Get Payment Method

Source: https://docs.getreditus.com/llms.txt

Retrieve the masked payment method for an advocate. Useful for displaying a 'connected' state without exposing sensitive data.

```APIDOC
## GET /v1/advocates/{identifier}/payment_method

### Description
Retrieves the masked payment method for an advocate.

### Method
GET

### Endpoint
/v1/advocates/{identifier}/payment_method

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The Reditus ID (UUID) or your internal user ID (uid) of the advocate.

### Response
#### Success Response (200 OK)
- **payment_type** (string) - The type of payment method (e.g., 'IBAN', 'PayPal').
- **masked_details** (object) - An object containing anonymized payment details.
  - Example: `{"masked_iban_last4": "**** **** **** 1234"}` or `{"masked_paypal_email": "***@example.com"}`
```

--------------------------------

### Show affiliate

Source: https://docs.getreditus.com/llms.txt

Show data for a partner.

```APIDOC
## Show affiliate

### Description
Show data for a partner.

### Method
GET

### Endpoint
/v1/partners/show.md
```

--------------------------------

### Load Referral Widget

Source: https://docs.getreditus.com/referral-program/loading

Invoke this method where your frontend has access to user data and the JWT token from your backend. It automatically fetches the referral program code and makes the widget available through `window.referralWidget`.

```javascript
const authToken = await fetchAuthToken();

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

--------------------------------

### Show Lead

Source: https://docs.getreditus.com/llms.txt

Show data for a specific lead.

```APIDOC
## GET /v1/leads/{lead_id}

### Description
Retrieves details for a specific lead.

### Method
GET

### Endpoint
/v1/leads/{lead_id}

### Parameters
#### Path Parameters
- **lead_id** (string) - Required - The unique ID of the lead.

### Response
#### Success Response (200 OK)
- **lead_id** (string) - The unique ID of the lead.
- **advocate_id** (string) - The ID of the advocate who referred this lead.
- **email** (string) - The email address of the lead.
- **created_at** (string) - The timestamp when the lead was created.
```

--------------------------------

### Create Advocate

Source: https://docs.getreditus.com/llms.txt

Create an advocate for your referral program. Advocates are individuals who can refer new customers.

```APIDOC
## POST /v1/advocates

### Description
Creates a new advocate for the referral program.

### Method
POST

### Endpoint
/v1/advocates

### Request Body
- **uid** (string) - Required - Your internal user ID for the advocate.
- **email** (string) - Optional - The email address of the advocate.
- **name** (string) - Optional - The name of the advocate.

### Response
#### Success Response (201 Created)
- **advocate_id** (string) - The unique Reditus ID (UUID) of the created advocate.
- **uid** (string) - Your internal user ID for the advocate.
- **created_at** (string) - The timestamp when the advocate was created.
```

--------------------------------

### Show Subscription

Source: https://docs.getreditus.com/llms.txt

Show data for a subscription

```APIDOC
## Show Subscription

### Description
Show data for a subscription

### Method
GET

### Endpoint
/v1/subscriptions/show.md
```

--------------------------------

### Create Payment

Source: https://docs.getreditus.com/llms.txt

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`.

```APIDOC
## Create Payment

### Description
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`.

### Method
POST

### Endpoint
/v1/payments/create.md
```

--------------------------------

### Initialize Reditus Tracking Script

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

This script initializes the Reditus tracking functionality and tracks a page view. Replace 'YOUR-REDITUS-UID' with your actual Reditus User ID. Ensure this script is added to all pages and subdomains.

```javascript
<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>
```

--------------------------------

### Show Payment

Source: https://docs.getreditus.com/llms.txt

Show data for a payment.

```APIDOC
## Show Payment

### Description
Show data for a payment.

### Method
GET

### Endpoint
/v1/payments/show.md
```

--------------------------------

### Track Conversion API Endpoint (OpenAPI V3)

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

This OpenAPI specification defines the POST /v2/tracking/conversion endpoint for tracking referrals. It details request body schemas, including required fields like affiliate_slug or advocate_slug, and email or uid. It also outlines possible responses for successful conversions, invalid requests, and existing referrals.

```yaml
POST /v2/tracking/conversion
openapi: 3.1.0
info:
  title: Reditus API - Tracking V2
  description: API specification for tracking conversions in Reditus (Version 2).
  version: 1.0.0
servers:
  - url: https://api.getreditus.com/api
security: []
paths:
  /v2/tracking/conversion:
    post:
      summary: Referral Conversion
      description: The tracking API allows you to track conversions for any affiliate.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackingV2Request'
      responses:
        '201':
          description: Successful conversion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackingV2Response'
        '400':
          description: Invalid affiliate slug
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    default: Invalid request
        '409':
          description: Referral already exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    default: Referral already exists
      security:
        - BearerAuth: []
components:
  schemas:
    TrackingV2Request:
      type: object
      properties:
        affiliate_slug:
          type: string
          description: >-
            URL parameter of the affiliate (i.e. https://company.com?red=john ->
            john). You can use a competitor slug as well.
        advocate_slug:
          type: string
          description: >-
            **required** if affiliate_slug is not set - URL parameter of the
            advocate (i.e. https://company.com?refby=jwe512 -> jwe512).
        email:
          type: string
          description: '**required** if uid is not set - Email of the referral'
        uid:
          type: string
          description: >-
            **required** if email is not set - Your internal ID of the
            user/customer
        gr_id:
          type: string
          description: >-
            Cookie set by the tracking script in the referral's browser. Used to
            match the exact click that converted.
      required:
        - affiliate_slug
    TrackingV2Response:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
            type:
              type: string
            attributes:
              type: object
              properties:
                email:
                  type: string
                uid:
                  type: string
                state:
                  type: string
                state_set_at:
                  type: integer
                created_at:
                  type: integer
                updated_at:
                  type: integer
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

```

--------------------------------

### Show Referral Widget Programmatically

Source: https://docs.getreditus.com/referral-program/show

Invoke this JavaScript method to instantly display the in-app referral modal. Link this action to a UI element like a button.

```javascript
window.referralWidget.show();
```

--------------------------------

### Show Partnership

Source: https://docs.getreditus.com/llms.txt

Show data for a partnership.

```APIDOC
## Show Partnership

### Description
Show data for a partnership.

### Method
GET

### Endpoint
/v1/partnerships/show.md
```

--------------------------------

### Authenticating the User

Source: https://docs.getreditus.com/llms.txt

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

```APIDOC
## POST /auth/jwt

### Description
Generates a JSON Web Token (JWT) for user authentication.

### Method
POST

### Endpoint
/auth/jwt

### Request Body
- **user_id** (string) - Required - The unique identifier for the user.
- **external_id** (string) - Optional - An external identifier for the user.

### Response
#### Success Response (200 OK)
- **token** (string) - The generated JWT.
```

--------------------------------

### Show Referral

Source: https://docs.getreditus.com/llms.txt

Show data for a referral.

```APIDOC
## Show Referral

### Description
Show data for a referral.

### Method
GET

### Endpoint
/v1/referrals/show.md
```

--------------------------------

### Create Payment

Source: https://docs.getreditus.com/llms.txt

Add a payment for a referral or lead. Can be used for one-off payments or recurring subscriptions.

```APIDOC
## POST /v1/payments

### Description
Adds a payment for a referral or lead.

### Method
POST

### Endpoint
/v1/payments

### Request Body
- **lead_id** (string) - Optional - The ID of the lead for which the payment is made. If not provided, a referral ID should be used.
- **advocate_id** (string) - Required - The ID of the advocate receiving the payment.
- **amount** (number) - Required - The payment amount.
- **currency** (string) - Required - The currency of the payment (e.g., 'USD', 'EUR').
- **description** (string) - Optional - A description for the payment.
- **subscription_id** (string) - Optional - The ID of the subscription if this payment is part of a recurring schedule.
- **interval** (string) - Optional - The interval for recurring payments (e.g., 'monthly', 'yearly').
- **interval_count** (integer) - Optional - The number of intervals for recurring payments.
```

--------------------------------

### List affiliates

Source: https://docs.getreditus.com/llms.txt

Retrieve a paginated list of partners.

```APIDOC
## List affiliates

### Description
Retrieve a paginated list of partners.

### Method
GET

### Endpoint
/v1/partners/index.md
```

--------------------------------

### List Leads

Source: https://docs.getreditus.com/llms.txt

Retrieve a paginated list of leads generated through your referral program.

```APIDOC
## GET /v1/leads

### Description
Retrieves a paginated list of leads.

### Method
GET

### Endpoint
/v1/leads

### Query Parameters
- **page** (integer) - Optional - The page number to retrieve (default: 1).
- **per_page** (integer) - Optional - The number of leads per page (default: 20).
- **advocate_id** (string) - Optional - Filter leads by a specific advocate ID.

### Response
#### Success Response (200 OK)
- **leads** (array) - A list of lead objects.
  - Each object contains: `lead_id`, `advocate_id`, `email`, `created_at`.
- **pagination** (object) - Pagination details.
  - Contains: `current_page`, `per_page`, `total_pages`, `total_count`.
```

--------------------------------

### Implement Referral Button in React

Source: https://docs.getreditus.com/referral-program/show

Use this React component to create a button that triggers the referral modal. Ensure the referral widget is initialized before calling show().

```javascript
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;
```

--------------------------------

### Track Conversion (Deprecating)

Source: https://docs.getreditus.com/llms.txt

The tracking API allows you to track conversions for any affiliate. Use V2 Instead.

```APIDOC
## Track Conversion (Deprecating)

### Description
The tracking API allows you to track conversions for any affiliate. Use V2 Instead.

### Method
POST

### Endpoint
/v1/tracking/conversion.md
```

--------------------------------

### Verify Webhook Signature in Go

Source: https://docs.getreditus.com/webhooks/get_started

Implement webhook signature verification in Go to ensure requests originate from Reditus. This involves calculating the HMAC-SHA256 hash of the raw body and comparing it with the `X-Signature` header.

```go
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))
}
```

--------------------------------

### List Commissions

Source: https://docs.getreditus.com/llms.txt

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.

```APIDOC
## List Commissions

### Description
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.

### Method
GET

### Endpoint
/v1/affiliate_commissions/index.md
```

--------------------------------

### Server Responses

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

Understanding common server responses is crucial for interacting with the Reditus Affiliate Programs API. This includes success codes like 200 OK and 201 Created, and various error codes such as 400 Bad Request and 404 Not Found.

```APIDOC
## 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.
```

--------------------------------

### List Referrals

Source: https://docs.getreditus.com/llms.txt

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.

```APIDOC
## List Referrals

### Description
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.

### Method
GET

### Endpoint
/v1/affiliate_referrals/index.md
```

--------------------------------

### List Partnerships

Source: https://docs.getreditus.com/llms.txt

Retrieve a paginated list of partnerships.

```APIDOC
## List Partnerships

### Description
Retrieve a paginated list of partnerships.

### Method
GET

### Endpoint
/v1/partnerships/index.md
```

--------------------------------

### Referral Conversion

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

The tracking API allows you to track conversions for any affiliate. This endpoint records a successful conversion event.

```APIDOC
## POST /v2/tracking/conversion

### Description
Records a referral conversion event.

### Method
POST

### Endpoint
/v2/tracking/conversion

### Request Body
- **affiliate_slug** (string) - Required - URL parameter of the affiliate (i.e. https://company.com?red=john -> john). You can use a competitor slug as well.
- **advocate_slug** (string) - Optional - **required** if affiliate_slug is not set - URL parameter of the advocate (i.e. https://company.com?refby=jwe512 -> jwe512).
- **email** (string) - Optional - **required** if uid is not set - Email of the referral.
- **uid** (string) - Optional - **required** if email is not set - Your internal ID of the user/customer.
- **gr_id** (string) - Optional - Cookie set by the tracking script in the referral's browser. Used to match the exact click that converted.

### Request Example
```json
{
  "affiliate_slug": "john",
  "email": "referral@example.com",
  "gr_id": "some_cookie_value"
}
```

### Response
#### Success Response (201)
- **data** (object) - Contains the details of the created conversion.
  - **id** (string) - The unique identifier for the conversion.
  - **type** (string) - The type of the resource, typically "conversion".
  - **attributes** (object) - Additional attributes of the conversion.
    - **email** (string) - The email of the referral.
    - **uid** (string) - The internal user ID of the referral.
    - **state** (string) - The current state of the conversion.
    - **state_set_at** (integer) - Timestamp when the state was last set.
    - **created_at** (integer) - Timestamp when the conversion was created.
    - **updated_at** (integer) - Timestamp when the conversion was last updated.

#### Response Example
```json
{
  "data": {
    "id": "conv_12345",
    "type": "conversion",
    "attributes": {
      "email": "referral@example.com",
      "uid": null,
      "state": "pending",
      "state_set_at": 1678886400,
      "created_at": 1678886400,
      "updated_at": 1678886400
    }
  }
}
```

#### Error Response (400)
- **error** (string) - Description of the error, e.g., "Invalid request".

#### Error Response (409)
- **error** (string) - Description of the error, e.g., "Referral already exists".

### Security
- Bearer Token Authentication
```

--------------------------------

### Track Conversion

Source: https://docs.getreditus.com/llms.txt

The tracking API allows you to track conversions for any affiliate.

```APIDOC
## POST /v2/tracking/conversion

### Description
Tracks a conversion event for an affiliate.

### Method
POST

### Endpoint
/v2/tracking/conversion

### Request Body
- **affiliate_id** (string) - Required - The ID of the affiliate who generated the conversion.
- **conversion_type** (string) - Required - The type of conversion (e.g., 'purchase', 'signup').
- **conversion_value** (number) - Optional - The value associated with the conversion.
- **timestamp** (string) - Optional - The timestamp of the conversion event (ISO 8601 format).
```

--------------------------------

### Track Conversion

Source: https://docs.getreditus.com/llms.txt

The tracking API allows you to track conversions for any affiliate.

```APIDOC
## Track Conversion

### Description
The tracking API allows you to track conversions for any affiliate.

### Method
POST

### Endpoint
/v2/tracking/conversion.md
```

--------------------------------

### Track Conversion in React JS

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

Call the `gr` function to track a conversion event after a successful sign-up in a React application. Ensure the `gr` function is available before calling it.

```javascript
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!');
    });
}
```

--------------------------------

### List Reward Triggers

Source: https://docs.getreditus.com/llms.txt

Retrieve a paginated list of reward triggers configured for your referral program.

```APIDOC
## GET /v1/reward_triggers

### Description
Retrieves a paginated list of reward triggers.

### Method
GET

### Endpoint
/v1/reward_triggers

### Query Parameters
- **page** (integer) - Optional - The page number to retrieve (default: 1).
- **per_page** (integer) - Optional - The number of reward triggers per page (default: 20).

### Response
#### Success Response (200 OK)
- **reward_triggers** (array) - A list of reward trigger objects.
  - Each object contains details about the trigger conditions and reward amounts.
- **pagination** (object) - Pagination details.
```

--------------------------------

### Track Conversion with Stripe Customer ID

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

Use the Stripe Customer ID with the Reditus snippet to track conversions. Ensure the `uid` parameter matches the Stripe Customer ID.

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

--------------------------------

### Verify Webhook Signature in Ruby

Source: https://docs.getreditus.com/webhooks/get_started

Use this code to verify the authenticity of incoming webhook requests by comparing the provided signature with a locally generated one. Requires the `openssl` and `rack` gems.

```ruby
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
```
Tokens:
Raw