Documentation

Welcome to the Mercadeo platform documentation. This guide covers the platform's core concepts, features, and API reference.

New to Mercadeo? Start with Core Concepts to understand the platform's architecture and principles.

Core Concepts

Mercadeo is a Performance Infrastructure Platform (PIP) built on three non-negotiable principles:

  • Financial Discipline — No campaign launches without funding commitment. Every financial movement is tracked in a double-entry wallet ledger.
  • Automated Risk Enforcement — Risk scoring happens at the creator, brand, and cross-campaign level. Fraud signals propagate network-wide.
  • Immutable Performance Trust — Commission terms lock at campaign activation. No retroactive edits. Attribution windows lock. The system governs, not a person.

Architectural Guardrails

  1. Append-only event logs — All conversions, refunds, payouts, and risk recalculations are immutable
  2. No retroactive commission edits — Once a campaign is active, terms are locked
  3. Attribution rule locking — Attribution type and window lock at activation
  4. No manual ledger editing — All adjustments generate system events with audit trails
  5. System-triggered payouts — Release scheduler executes automatically; risk score gates must pass

Roles

  • Brand — Creates campaigns, manages offers, reviews content, approves creators, funds wallets
  • Creator — Enrolls in campaigns, tracks earnings, submits content, manages disputes
  • Admin — Platform operations, user management, dispute escalation, policy configuration, observability

Onboarding

Authentication Methods

  • Email + OTP — Passwordless one-time-password via email
  • Magic Link — One-click login link sent to email (15-minute expiry)
  • Social OAuth — LinkedIn, X (Twitter), TikTok, Meta
  • MFA/TOTP — Optional two-factor authentication via authenticator app

Onboarding Flow

Brands complete a 9-step onboarding wizard (company info, branding, payment setup, first campaign). Creators complete a 7-step flow (profile, social accounts, niche selection, portfolio).

Invite Codes

Admins can generate invite codes to control platform access. Codes can be single-use or multi-use with expiration dates.

Campaigns

Campaign Lifecycle

Campaigns follow a strict state machine: DRAFT → PENDING_REVIEW → ACTIVE → PAUSED → COMPLETED → ARCHIVED

Important: Once a campaign moves to ACTIVE, commission structures, attribution rules, and funding mode are permanently locked.

Campaign Frameworks

  • Framework A — Standard affiliate (percentage or fixed commission per conversion)
  • Framework B — Tiered commission (escalating rates based on volume)
  • Framework C — Milestone-based (payouts triggered at specific thresholds)

Offers & Enrollment

Each campaign contains one or more offers. Creators apply to offers; brands approve or reject applications. Offer terms include commission type, rate, attribution window, and hold period.

Readiness Check

Before activation, campaigns must pass a readiness check: funding commitment verified, at least one offer configured, attribution rules set, and compliance review passed.

GET /api/v1/campaigns/:id/readiness

{
  "ready": true,
  "checks": {
    "funding": "passed",
    "offers": "passed",
    "attribution": "passed",
    "compliance": "passed"
  }
}

Tracking & Attribution

Tracking Methods

  • JavaScript Snippet — Client-side tracking via mercadeo-tracker.js
  • Server-Side API — Direct conversion ingestion via REST API
  • Subscription Events — Recurring revenue tracking for SaaS

Attribution Models

Attribution type (first-click or last-click) and window duration lock at campaign activation and cannot be modified during the campaign lifecycle.

Conversion Ingestion

POST /api/v1/ingest/conversions
Content-Type: application/json
Authorization: Bearer <token>

{
  "orderId": "order_123",
  "amount": 99.99,
  "currency": "USD",
  "customerEmail": "[email protected]",
  "metadata": { "plan": "pro" }
}

Refund Handling

POST /api/v1/ingest/refunds
{
  "orderId": "order_123",
  "amount": 99.99,
  "reason": "customer_request"
}

Wallets & Ledger

Mercadeo uses a double-entry wallet ledger system. Every financial movement creates balanced debit and credit entries.

Wallet Types

  • Brand Wallet — Holds campaign funding, debited on commission approval
  • Creator Wallet — Credited on commission approval, debited on payout
  • Platform Wallet — Receives take-rate fees and acceleration fees
  • Hold Reserve — Tracks funds in hold period before release (funds remain with payment processor)

Ledger Entries

All ledger entries are append-only. Corrections are made via new offsetting entries, never by modifying existing records.

Payouts & Releases

Release Scheduler

Payouts are deterministic and policy-driven. The release scheduler automatically processes eligible payouts when:

  1. Hold period has elapsed
  2. Risk score gate passes (combined rule-based 60% + anomaly-based 40%)
  3. Minimum payout threshold is met
  4. No active disputes on the conversion

Release Decision Matrix

  • Score < 30 — Auto-release
  • Score 30-49 — Extend hold period
  • Score 50-69 — Manual review required
  • Score 70+ — Freeze and escalate

Payout Acceleration

Creators can request early payout for a risk-adjusted fee (1-3% based on tier). Acceleration fees are recorded as platform revenue.

Platform Take Rate

Tier-based platform fees (5-10%) are automatically calculated and recorded in the platform wallet ledger.

Risk & Fraud

Risk Scoring

Every creator and brand receives a dynamic risk score based on:

  • Reversal/refund rates
  • Dispute frequency
  • Conversion velocity patterns
  • Cross-campaign behavior analysis

Cross-Campaign Risk Graph

Risk signals propagate across campaigns. If a creator shows suspicious patterns in one campaign, the risk score affects all their active campaigns.

ML Anomaly Detection

Baseline metrics are computed per creator and campaign. Statistical anomaly detection identifies deviations in conversion patterns, amounts, and timing. Combined scoring: rule-based (60%) + anomaly-based (40%).

Disputes

Structured dispute workflows with evidence submission, escalation, and resolution.

Dispute Lifecycle

OPEN → UNDER_REVIEW → ESCALATED → RESOLVED

  • Both parties can submit evidence (files, screenshots, links)
  • Disputes must be filed within 30 days of the transaction
  • Admin escalation available for complex cases
  • Resolution outcomes: approved, rejected, partial

Messaging

Direct in-app messaging between brands and creators. Conversations are organized by campaign context.

POST /api/v1/messages
{
  "conversationId": "conv_abc",
  "content": "Looking forward to the campaign launch!",
  "recipientId": "user_xyz"
}

Content Approval

Brands can require content review before publication. Creators submit content; brands approve, request revisions, or reject.

Content submission lifecycle: SUBMITTED → IN_REVIEW → APPROVED / REVISION_REQUESTED / REJECTED

Authentication

All API requests require a JWT bearer token:

Authorization: Bearer <your-jwt-token>

Login

POST /api/v1/auth/login
{ "email": "[email protected]", "otp": "123456" }

// Response
{ "token": "eyJ...", "user": { "id": "...", "role": "BRAND" } }

Magic Link

POST /api/v1/auth/magic-link
{ "email": "[email protected]" }
// User receives a login link valid for 15 minutes

API Endpoints

Mercadeo exposes 70+ REST API endpoints under /api/v1/. Key groups:

Authentication

  • POST /api/v1/auth/register
  • POST /api/v1/auth/login
  • POST /api/v1/auth/magic-link
  • GET /api/v1/auth/me
  • POST /api/v1/auth/mfa (setup/verify)
  • GET /api/v1/auth/oauth/:provider

Campaigns & Offers

  • GET/POST /api/v1/campaigns
  • GET/PATCH /api/v1/campaigns/:id
  • POST /api/v1/campaigns/:id/activate
  • POST /api/v1/campaigns/:id/pause
  • GET /api/v1/campaigns/:id/readiness
  • GET/POST /api/v1/offers
  • POST /api/v1/offers/:id/terms/change-request
  • GET /api/v1/offers/:id/versions
  • GET /api/v1/offers/:id/applications

Tracking & Conversions

  • POST /api/v1/ingest/conversions
  • POST /api/v1/ingest/refunds
  • POST /api/v1/ingest/subscription-events
  • GET /api/v1/conversions
  • GET /api/v1/conversions/:id

Financial

  • GET /api/v1/wallets
  • GET /api/v1/wallets/ledger
  • GET /api/v1/ledger-entries
  • GET/POST /api/v1/payouts
  • POST /api/v1/payouts/accelerate
  • GET /api/v1/releases
  • GET /api/v1/releases/:id
  • GET /api/v1/refunds

Risk & Disputes

  • GET /api/v1/risk/graph
  • GET /api/v1/anomaly
  • GET/POST /api/v1/disputes
  • POST /api/v1/disputes/:id/submit-evidence
  • POST /api/v1/disputes/:id/escalate
  • POST /api/v1/disputes/:id/resolve

Platform

  • GET/POST /api/v1/messages
  • GET/POST /api/v1/content-submissions
  • GET/POST /api/v1/enrollments
  • GET /api/v1/notifications
  • GET/POST /api/v1/webhooks
  • GET /api/v1/events/stream (SSE)
  • GET/POST /api/v1/policies
  • GET /api/v1/marketplace
  • GET /api/v1/observability
  • GET/POST /api/v1/security
  • GET /api/v1/health

Webhooks

Configure webhook endpoints to receive real-time notifications. All payloads are signed with HMAC-SHA256 and include automatic retry with exponential backoff.

Event Types (12)

  • affiliate.created / approved / rejected
  • referral.submitted / approved
  • commission.created / paid
  • payout.requested / completed / failed
  • content.submitted
  • message.sent

Signature Verification

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Event Stream

Real-time Server-Sent Events (SSE) for live platform updates:

GET /api/v1/events/stream
Accept: text/event-stream
Authorization: Bearer <token>

// Events stream in real-time:
data: {"type":"conversion.recorded","data":{...}}
data: {"type":"payout.released","data":{...}}

Policy Engine

Versioned policies control platform behavior. Policies are typed (e.g., payout, risk, dispute) and only one policy of each type can be active at a time. Activating a new policy automatically deactivates the previous one.

Feature Flags

Platform features can be toggled via the feature flag system without code deployment.

Observability

The admin observability dashboard provides four views:

  • Health — Platform uptime, response times, error rates, service status
  • Events — Event volume, type distribution, processing latency
  • Reconciliation — Ledger balance verification, orphaned entries, mismatches
  • Trace — Request tracing for debugging and performance analysis

Alerting Thresholds

Automatic alerts trigger when refund rates, dispute rates, webhook failure rates, or pending payout amounts exceed configured thresholds.

Security

  • Rate Limiting — Per-category limits (auth: 10/5min, conversion: 50/min, webhook: 200/min, default: 100/min)
  • Maker-Checker — High-impact operations require approval from a second admin
  • Impersonation — Admins can impersonate users for debugging with full audit trail
  • Webhook Replay Protection — Timestamp-based replay attack prevention
  • Idempotency — All write operations support idempotency keys to prevent duplicate processing
  • RBAC — Role-based access control with scoped permissions per organization