CRM & Loyalty

Every CRM endpoint requires a valid JWT or API key sent as Authorization: Bearer <token>. The base URL for all requests is https://gullypay.xyz/api. Contact, campaign, and loyalty resources are scoped to a merchant via the :merchantId path segment; loyalty sub-resources additionally verify that the program belongs to that merchant.

Contacts store customer profiles with free-form tags — there is no separate segment resource; segmentation is done by filtering on tags (the campaign send endpoint accepts an optional tag to narrow the audience). Campaigns can now be sent: sending snapshots the target audience into campaign_recipients rows and transitions the campaign to sent.

Sending a campaign or running an automation persists the target audience as real campaign_recipients rows with status queued and records the real audience size — it does not hand messages to a live email/SMS provider. Actual transport is a provider swap (the same pattern as the Stripe mock): recipients stay queued and are never reported as delivered. openCount/clickCount remain a real 0 until a provider reports delivery events. Wire a transport provider to flip recipient status and increment those counters.

{
"email": "[email protected]",
"name": "Jordan Lee",
"phone": "+15551234567",
"tags": ["vip", "newsletter"]
}

{
"name": "Summer Sale",
"type": "email",
"subject": "20% off everything",
"body": "Our biggest sale of the year is here."
}

{
"tag": "vip"
}

{
"id": "cmp_abc123",
"status": "sent",
"sentCount": 128,
"recipientCount": 128,
"queued": 128
}

{
"name": "Welcome series",
"trigger": "welcome",
"actionType": "email",
"status": "active",
"config": { "template": "welcome-1" }
}

{
"name": "Rewards Club",
"pointsPerDollar": 10
}

[
{
  "id": "loy_abc123",
  "merchantId": "merch_abc123",
  "name": "Rewards Club",
  "pointsPerDollar": 10,
  "memberCount": 128,
  "totalPoints": 45200,
  "lifetimeEarned": 61000
}
]

{
"programs": 1,
"totalMembers": 128,
"pointsIssued": 61000,
"pointsRedeemed": 15800,
"pointsOutstanding": 45200,
"recentMembers": [
  { "programId": "loy_abc123", "userId": "usr_1", "balance": 320, "lifetimeEarned": 900, "updatedAt": "2026-06-09T12:00:00Z" }
],
"tiers": [
  { "id": "tier_1", "programId": "loy_abc123", "name": "Gold", "minPoints": 500, "sortOrder": 2, "memberCount": 12 }
],
"rewards": [
  { "id": "rwd_1", "programId": "loy_abc123", "name": "Free shipping", "pointsCost": 200, "active": 1 }
],
"recentRedemptions": [
  { "id": "rdm_1", "programId": "loy_abc123", "userId": "usr_1", "rewardId": "rwd_1", "pointsSpent": 200, "status": "pending", "rewardName": "Free shipping", "userEmail": "[email protected]" }
]
}

{
"name": "Gold",
"minPoints": 500,
"sortOrder": 2,
"perks": { "discount": "10%" }
}

{
"name": "Free shipping",
"description": "One free shipment",
"pointsCost": 200,
"active": true
}

{
"userId": "usr_1",
"rewardId": "rwd_1"
}

{
"id": "rdm_1",
"programId": "loy_abc123",
"userId": "usr_1",
"rewardId": "rwd_1",
"pointsSpent": 200,
"status": "pending",
"balanceAfter": 120
}

{
"code": "JORDAN10",
"commissionRate": 10
}

{
"referredUserId": "usr_2",
"commission": 500
}

{
"affiliates": 4,
"total": 37,
"byStatus": { "pending": 12, "confirmed": 25 },
"totalCommission": 18400
}

{
"totalOwed": 30000,
"affiliates": [
  { "affiliateId": "af_1", "code": "JORDAN10", "status": "active", "commissionRate": 10, "earned": 50000, "totalPaid": 20000, "owed": 30000 }
]
}

{
"id": "po_1",
"affiliateId": "af_1",
"amount": 30000,
"status": "paid",
"affiliateCode": "JORDAN10"
}

{
"count": 3,
"totalPaid": 30000,
"payouts": [
  { "id": "po_1", "affiliateId": "af_1", "amount": 30000, "status": "paid" }
]
}