Tracking Referrals

import dash from "@/lib/dash"

const result = await dash.referrals.validate({
  secret: "ref_abc123",  // referral secret from URL
  subtotal: "99.99",
})

// result = {
//   valid: true,
//   referrer_first_name: "John",
//   code: "JOHNS-REF",
//   is_percentage: true,
//   rate: "15",
//   discount_amount: "15.00",
//   meetsMinimum: true
// }

// Authenticated customer
const dashboard = await dash.referrals.dashboard()

// dashboard = {
//   referral_secret: "ref_abc123",
//   referral_link: "https://yourstore.com/?ref=ref_abc123",
//   total_referrals: 12,
//   total_points_earned: 600,
//   points_balance: 250,
//   recent_referrals: [...]
// }

// On storefront, check for referral param in URL
const ref = new URLSearchParams(window.location.search).get("ref")
if (ref) {
  // Store the referral secret for checkout
  localStorage.setItem("referral_secret", ref)

  // Validate and auto-apply discount
  const result = await dash.referrals.validate({
    secret: ref,
    subtotal: cartSubtotal,
  })

  if (result.valid) {
    await dash.cart.applyDiscount(result.code)
  }
}

# Validate referral
POST /storefront/referrals/validate
Content-Type: application/json
{ "secret": "ref_abc123", "subtotal": "99.99" }

# Referral dashboard (authenticated)
GET /storefront/referrals/dashboard
Authorization: Bearer {access_token}