Growth & Partner API

The Growth API covers two systems:

UTM attribution: track where visitors came from (Google Ads, Instagram, partner blogs, etc.)
Partner program: manage affiliate partners, referrals, and commissions

UTM Attribution

Record a visit

Call this on page load to record a UTM-tagged visit. The frontend SDK does this automatically via useUtmCapture.

POST /growth/utm/visit
Content-Type: application/json

{
  "sessionId": "ks_abc123",
  "utmSource": "google",
  "utmMedium": "cpc",
  "utmCampaign": "summer_launch",
  "referralCode": "EMMAB2C",
  "landingPage": "https://kerabie.com/?utm_source=google&utm_medium=cpc"
}

When a user signs up, pass the same UTM fields in the registration payload. The backend links the visit and credits the partner automatically.

UTM analytics summary

GET /growth/utm/analytics?days=30
Authorization: Bearer YOUR_API_KEY

{
  "period": "30d",
  "visits": 1240,
  "conversions": 87,
  "conversionRate": 7.0,
  "topSources": [
    { "source": "google", "count": 542 },
    { "source": "instagram", "count": 311 }
  ],
  "topCampaigns": [
    { "campaign": "summer_launch", "count": 398 }
  ]
}

UTM timeline

GET /growth/utm/timeline?days=30
Authorization: Bearer YOUR_API_KEY

Returns daily visit and conversion counts for charting.

Partner Program

Apply as a partner

POST /partner/apply
Authorization: Bearer YOUR_API_KEY

{
  "displayName": "TechBlog Nigeria",
  "website": "https://techblog.ng",
  "description": "I write about SaaS tools for African businesses",
  "referralCode": "TECHBLOG"
}

Partners start with pending_review status. Once approved, they get a referral link: https://kerabie.com/?ref=TECHBLOG

Partner dashboard

GET /partner/me
Authorization: Bearer YOUR_API_KEY

Returns the partner profile, recent referrals, earnings, and payouts.

Earnings breakdown

GET /partner/earnings?days=30
Authorization: Bearer YOUR_API_KEY

{
  "summary": {
    "totalEarned": 25000,
    "totalPaid": 10000,
    "pendingBalance": 15000,
    "totalClicks": 342,
    "totalSignups": 18
  },
  "earnings": [...],
  "timeline": [
    { "date": "2026-06-01", "earned": 5000, "pending": 5000, "paid": 0 }
  ]
}

Verify a referral code

GET /partner/verify/{code}

{
  "valid": true,
  "partner": {
    "referralCode": "TECHBLOG",
    "displayName": "TechBlog Nigeria"
  }
}

Request payout

POST /partner/payout/request
Authorization: Bearer YOUR_API_KEY

{ "amount": 10000 }

Payouts are processed within 2–3 business days to the partner's registered bank account.

How UTM flows to Partner commission

Visitor lands on kerabie.com/?ref=TECHBLOG
Frontend calls POST /growth/utm/visit with referralCode: "TECHBLOG"
Partner's totalClicks increments
Visitor signs up: registration payload includes referralCode, utmSessionId
Backend links the UtmVisit → creates PartnerReferral → increments totalSignups
When visitor subscribes to a paid plan → PartnerEarning is created (20% commission)

Growth & Partner API

On this page