Purchase Attribution System

Marketing Touchpoint          Purchase Event           Attribution Record
------------------           ---------------          -------------------
Link Open                    →  Customer              → Campaign Performance
├─ tracking_id                  ├─ Same tracking_id    ├─ Revenue attributed
├─ UTM parameters               ├─ Purchase data       ├─ Time to conversion
└─ Timestamp                    └─ Timestamp           └─ Campaign details

     OR

Loyalty Accumulation         →  Purchase Event        → Loyalty Attribution
├─ Reward earned                ├─ event_id            ├─ Revenue attributed
├─ event_id                     ├─ Redemption          ├─ Time to conversion
└─ Timestamp                    └─ Timestamp           └─ Loyalty impact

{
  "marketing_automation_links": 10080, // 7 days in minutes
  "marketing_automation_emails": 2880, // 2 days in minutes
  "marketing_automation_push": 1440, // 1 day in minutes
  "loyalty": 43200 // 30 days in minutes
}

https://yourapp.com/products?ad_provider=meta&utm_source=facebook&utm_campaign=summer-sale

const attribution = {
  tracking_id: "generated-tracking-id",
  ad_provider: "meta" // Only when not coming from link redirect
};

// When customer clicks marketing link and lands in your app
const tracking_id = extractTrackingId(window.location.href);
const ad_provider = new URLSearchParams(window.location.search).get(
  "ad_provider"
);

// Store for later use
sessionStorage.setItem("masivo_tracking_id", tracking_id);
sessionStorage.setItem("masivo_ad_provider", ad_provider);

// When customer makes a purchase
const sendPurchaseEvent = async (purchaseData: {
  customer_id: string;
  brand_id: string;
  order_id: string;
  total: number;
  products: any[];
}) => {
  const tracking_id = sessionStorage.getItem("masivo_tracking_id");
  const ad_provider = sessionStorage.getItem("masivo_ad_provider");

  const eventPayload = {
    type: "PURCHASE",
    customer_id: purchaseData.customer_id,
    brand_id: purchaseData.brand_id,

    // Attribution object - critical for attribution tracking
    attribution: {
      tracking_id, // Links to marketing touchpoint
      ad_provider, // REQUIRED - identifies traffic source
      utm_source: "facebook", // Optional but recommended
      utm_medium: "social", // Optional but recommended
      utm_campaign: "summer-sale", // Optional but recommended
      revenue: purchaseData.total, // Enables ROI calculations
      cost: 5.5 // Optional: campaign cost per conversion
    },

    order: {
      purchase_id: purchaseData.order_id,
      value: purchaseData.total,
      products: purchaseData.products.map(p => ({
        sku: p.sku,
        amount: p.quantity,
        value: p.price
      })),
      payment_method: "CREDIT"
    }
  };

  const response = await fetch(
    "https://app.masivo.ai/api/storefront/v1/behavior/events",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(eventPayload)
    }
  );

  return response.json();
};

interface AttributionData {
  // Core Tracking
  tracking_id?: string; // UUID linking touchpoint to purchase

  // Provider Identification (CRITICAL)
  ad_provider?: string; // Must match configured provider name

  // UTM Parameters (Recommended)
  utm_source?: string; // Traffic source: "google", "facebook", "email"
  utm_medium?: string; // Medium: "cpc", "social", "email", "push"
  utm_campaign?: string; // Campaign name
  utm_term?: string; // Paid search keywords
  utm_content?: string; // Ad variation identifier
  utm_referral?: string; // Specific referral source

  // Financial Tracking
  revenue?: number; // Purchase value for ROI calculation
  cost?: number; // Acquisition cost for this conversion
}

Priority 1: Link/Email/Push attribution data
Priority 2: Purchase event attribution data
Priority 3: Default values (ad_provider: "unknown")

# Create a test link with attribution
curl -X POST https://app.masivo.ai/api/storefront/v1/links \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_url": "https://yourapp.com/products?ad_provider=meta",
    "attribution": {
      "ad_provider": "meta",
      "utm_source": "facebook",
      "utm_campaign": "test-campaign"
    }
  }'

# Click the generated short link
# Extract tracking_id from redirected URL
# Make a test purchase with that tracking_id

// 1. Create purchase that earns rewards
await sendPurchaseEvent({
  type: "PURCHASE",
  customer_id: "test-customer",
  order: {
    purchase_id: "order-1",
    value: 100
  }
});

// 2. Wait for reward accumulation
// 3. Create second purchase with redemption
await sendPurchaseEvent({
  type: "PURCHASE",
  customer_id: "test-customer",
  order: {
    purchase_id: "order-2",
    value: 150
  }
  // System automatically links via event_id
});

// Check attribution records to verify loyalty attribution

// ✅ GOOD - Clear provider identification
{
  ad_provider: "meta",
  tracking_id: "...",
  utm_source: "facebook"
}

// ❌ BAD - Missing provider defaults to "unknown"
{
  tracking_id: "...",
  utm_source: "facebook"
}

// Provider names must match exactly
// Dashboard: "meta"
// Code: "meta" ✓

// Dashboard: "Google Ads"
// Code: "google_ads" ✗ → Won't match!