Skip to content

Commission Booking & Affiliate Attribution — Tenant Admin User Manual

1. Overview & Operational Workflow

The Commission Booking Engine coordinates partner marketing attribution, automated commission calculations, holding periods, and payout workflows across your tenant workspace.

End-to-End Operational Lifecycle

  1. Prospect Clicks Monitored Link: A customer visits a custom partner link such as https://merp.ebosai.com/ref/partner-slug.
  2. Link Resolution & Cryptographic Cookie Placement: The platform checks the link's validity, dispatches an asynchronous background task to log the click (capturing IP, user agent, and browser fingerprint), sets a 30-day cryptographically signed attribution token cookie named amp_ref, and redirects the prospect to the destination landing page.
  3. Prospect Navigates & Completes Signup: The customer registers or purchases a subscription on your product landing page or portal.
  4. Attribution Ingestion: The client-side tracking script sends a lightweight conversion beacon containing pseudonymous order metadata and the signed attribution token to the Commission Engine.
  5. Commission Rate Calculation: A background Celery worker evaluates commission rules and computes the exact payout amount using a predefined priority hierarchy.
  6. Pending Queue Placement: The generated commission is placed in Pending status with an assigned holding period (typically 30 days) to accommodate refund and cancellation policies.
  7. Admin Pipeline Review & Approval: The Tenant Admin verifies and approves the commission in the Commissions Pipeline dashboard.
  8. Payout Batch Generation: Once the holding period elapses and minimum payout thresholds are met, the commission transitions to eligibility for batch payout processing.

2. How the Platform Calculates and Books Commissions

Partners (Affiliates and Influencers) receive tracked links with custom slugs (such as alex-cloud-tier), destination target URLs, active status flags, and optional expiration dates.

When a visitor accesses the public redirect path: - The system confirms that the link is active and unexpired. - A background worker records the click in the database for analytics and audit reporting. - A secure browser cookie (amp_ref) containing a tamper-proof cryptographically signed attribution token is created with a 30-day lifespan (2,592,000 seconds), configured with SameSite Lax and path root. - The visitor is redirected via HTTP 302 to the target URL.

Step 3: Attribution & Signup Event Ingestion

When a user completes registration or billing: - Priority 1 (Monitored Link Cookie/Query): The platform checks for the signed amp_ref cookie or a referral token parameter. If present, it attributes the signup to the specific partner, marks the event as commission-eligible, increments the partner's conversion count, and marks the most recent click from the past 30 days as converted. - Priority 2 (Marketplace Sources): If no partner link is found, the system checks marketing source tags against configured marketplaces (such as AppSumo or Lemon Squeezy). Signups from these sources are recorded but flagged as ineligible for partner commissions. - Priority 3 (Direct / Organic): If no marketing tags or cookies match, the signup is classified as organic or direct, with no commission generated.

Step 4: Commission Rate Waterfall Hierarchy

For all eligible signups, the calculation engine applies rates according to this strict waterfall order:

  1. Product-Specific Override (Highest Priority): If the purchased product has a designated commission override rate and type (percentage or flat fee), this rate takes immediate precedence.
  2. Partner-Specific Override: If no product override exists, the system checks for a custom commission rate or override set directly on the partner's profile.
  3. Affiliate Tier Defaults: If no custom partner rate is set, the system applies the rate assigned to the partner's tier (Standard, Silver, or Gold) as defined in tenant settings.
  4. Tenant Global Default (Base Fallback): If no tier or override applies, the system uses the global tenant commission rate and type.

Step 5: Commission Status Pipeline & State Transitions

  • Pending: Initial state upon calculation. The commission is held until its scheduled eligibility date.
  • Approved: Verified by the Tenant Admin, confirming the referral is legitimate.
  • Paid: Included and settled within a completed payout batch.
  • Rejected: Disapproved by the Admin due to fraud, self-referral, or invalid activity (requires a documented reason).
  • Cancelled: Voided following a customer refund or chargeback during the holding period.

3. Product Vendor Integration (Zero-Secret Client Script)

To connect any third-party product or monitored link host with the commission engine, product vendors do not need to build server-side APIs, configure webhooks, or store secret keys.

Integration Method 1: One-Line Script Tag on Success Page

Product vendors simply add a lightweight script tag to their registration success or checkout thank-you page:

Script Source: https://merp.ebosai.com/ref/track.js Script Attributes: - data-tenant: Your Tenant Workspace Identifier (UUID) - data-customer-id: Pseudonymous Customer or Company Identifier - data-amount: Transaction Monetary Value - data-currency: Currency Code (such as USD or AED) - data-plan: Subscription Plan Key (such as pro or enterprise)

When the customer lands on the success page, the script automatically extracts the signed attribution cookie, sends a secure conversion beacon in the background, and triggers commission booking.

Integration Method 2: JavaScript Function Call for Single-Page Applications

For React, Vue, or Next.js applications, vendors can trigger the conversion programmatically upon payment confirmation:

Function Call: window.ebosai.convert Parameters: - tenantId: Your Tenant Workspace Identifier (UUID) - customerId: Pseudonymous Customer or Company Identifier - amount: Transaction Monetary Value - currency: Currency Code (such as USD or AED) - plan: Subscription Plan Key (such as pro or enterprise)

4. GDPR Compliance & Data Privacy Guidelines

The integration is built strictly around privacy-by-design principles: - Zero Personal Data in Payloads: Only pseudonymous tokens (customer identifier, plan, amount, currency) are transmitted. Personal names, emails, and phone numbers are excluded from cross-system beacons. - First-Party Context: Attribution tokens are stored directly under the product origin host. - Statutory Audit Decoupling: If a customer deletes their personal account under GDPR Right to Erasure, financial commission records remain legally intact without retaining personal identifiable records.

5. Admin Pipeline Management & Troubleshooting

Pipeline Verification Checklist

  1. Verify the partner link is active and points to the correct product landing page.
  2. Confirm the success page includes the tracking tag with the matching tenant identifier.
  3. Review the Signup Events tab in the admin dashboard to inspect inbound attribution events.
  4. Check the Commissions tab to review pending rates, calculation waterfall sources, and holding periods.
  5. Approve eligible commissions before processing the scheduled payout batch.