Conversion

Description

Conversions are the core of the referral system, representing successful actions taken by referred users that trigger rewards for partners. A conversion occurs when a referred user performs a specific action (like making a purchase or subscribing) that meets the criteria defined in your reward rules.

Conversion Types

Currently, the system supports two main types of conversions:

Purchase Conversion

Purchase conversions track when a referred user makes a purchase. The payload includes:

• product_id (required): Unique identifier for the purchased product
• amount (required): The purchase amount (numeric)
• currency: The currency of the purchase
• category: Product category
• quantity: Number of items purchased (defaults to 1)
• user_agent: Browser/client information
• source: Where the purchase originated
• meta: Additional metadata about the purchase

Subscription Conversion

Subscription conversions track when a referred user subscribes to a service. The payload includes:

• plan: The subscription plan name
• amount (required): The subscription amount (numeric, minimum 0)
• currency: The currency of the subscription
• subscription_id: Unique identifier for the subscription
• user_agent: Browser/client information
• source: Where the subscription originated
• meta: Additional metadata about the subscription

Conversion Status

Conversions can have one of the following statuses:

• Pending: Initial state when a conversion is created
• Accepted: Conversion has been approved and rewards will be processed
• Rejected: Conversion has been rejected and no rewards will be given
• Suspicious: Flagged by the fraud detection system for review

How Conversions Work

1. When a conversion occurs, the system creates a new conversion record with the relevant data
2. The conversion is processed asynchronously through the ProcessReferralConversion job
3. The system checks for applicable reward rules based on:
   • The conversion type
   • The amount
   • Any specific conditions defined in the rules
4. If rules match, rewards are calculated and transactions are created
5. The conversion status is updated accordingly

Tracking Conversions

You can track conversions using the API endpoint /v1/convert or through the SDK:

nodiRef("track", "conversion", {
  referral_id: "REFERRAL_ID", // or external_id
  event_type: "purchase", // or "subscription"
  payload: {
    // Payload data based on conversion type
  }
});

For more details about the API endpoints and payload structure, check the API Reference.

Fraud Detection

The system automatically collects metadata for fraud detection, including:

• IP addresses
• User agent information
• Request headers
• Geographic data
• Device information

This data is used to identify potentially suspicious conversions and protect your referral program from abuse.

Reward Calculation

Rewards for conversions can be calculated in two ways:

1. Fixed Amount: A specific reward amount is given for each conversion
2. Percentage: A percentage of the conversion amount is given as reward

The system automatically handles the calculation based on your reward rule settings, including any maximum caps you've defined.