Overview

The Spotinga Affiliate System automates the complex journey from a customer click to a partner payout. As an administrator, your primary role is overseeing the “Resolution Trace” and authorizing payout batches.

Automatic Commission Calculation

When a sale is recorded via a partner link, the system creates an Conversion record. Immediately, the calculation engine runs to generate an Commission Calculation audit trail.

The Resolution Hierarchy

The engine doesn’t just pick a number; it scans multiple layers to find the most specific “Winning Plan” in this order:

1. Active Campaigns: If the sale falls within a campaign window and the partner is a participant.
2. Link Overrides: If the specific link used has a custom plan attached.
3. Partner Overrides: If the partner has a negotiated private rate.
4. Program Defaults: The fallback plan defined for your Organization.

Resolution Trace

You can view the Candidate Plans for any conversion. This shows every plan the partner was eligible for and why the “Selected Source” was chosen (usually driven by the priority field in the plan or campaign).

Financial Guardrails

To protect your margins, the system applies two levels of limits:

• Plan Caps: Each Affiliate Plan can have a Max Commission (e.g., never pay more than $50 on a single booking).
• Global Program Cap: Set via Global Max Commission. This ensures that even if a partner hits a high-tier “Step-up” bonus, the total payout never exceeds a fixed percentage of the Commissionable Amount.

Conversion Workflow

Commissions are not earned immediately. They follow a status lifecycle:

• Pending: The sale is recorded, but the “cooling off” period (Attribution Window) or the event date hasn’t passed.
• Approved: The administrator (or an automated trigger from the order system) confirms the sale is final. This moves the amount into the partner’s Pending Amount.
• Rejected: Used for cancelled orders or fraudulent activity. You must provide a Rejection Reason.
• Refunded: If a customer is refunded after approval, the system flags the commission to be clawed back or deducted from the next payout.

Multi-Tenant Payout Batches

Payouts are managed at the Organization level. While Spotinga is multi-tenant, each Org is responsible for its own partner liabilities.

Payout Requirements

A partner is only eligible for a payout batch if:

1. Their status is Active.
2. Their Pending Amount (approved commissions) meets or exceeds their Minimum Payout Threshold (default is 50).
3. They have valid Payout Details for their chosen Payout Method.

Processing a Batch

When you generate an PayoutBatch, the system:

• Groups all approved conversions within a Period Start and Period End.
• Calculates the total in the Partner’s chosen currency.
• Exports the data for your payment instrument (Stripe, Bank Transfer, PayPal, etc.).
• Updates the batch status to Processing until you confirm the Payout Reference (External Transaction ID).

Partner Currency & Instruments

Individual partners can operate in different regions. The model supports:

• Currency Conversion: The Commission Calculation records the conversion at the time of sale, but the final Payout Batch ensures the partner receives the value in their configured currency.
• Instruments: Supported methods include:
  • Bank Transfer (ACH/Wire)
  • Stripe (Connect - limited to few geographies)
  • Paypal
  • Store Credit (Issued as vouchers for your shop)
  • Crypto or Check (limited to few geographies)

Performance Snapshots

Because “Step-up” plans rely on lifetime performance, the system takes an Partner Snapshot.

• It aggregates Lifetime Revenue and Lifetime Conversions.
• It determines the Current Tier.
• This allows the next commission calculation to be instantaneous rather than recalculating the partner’s entire history on every sale.