Loyalty Programs

Loyalty programs are stamp-card-style reward schemes managed on the K42 platform and available to your members. A member collects qualifying purchases (stamps) and receives a reward once they reach the program's threshold.

How Loyalty Programs Work

1. Programs are configured on the K42 platform with a qualifying threshold and reward type
2. You list available programs and display them to your members
3. A member enrolls by creating a stamp collection
4. As the member makes qualifying purchases (via transaction ingestion), stamps are collected automatically
5. When the threshold is met, the reward is triggered automatically

Listing Available Programs

curl -X POST https://<your-instance-url>/publisher.v1/loyalty-program/list \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pagination": { "limit": 50 }
  }'

Response:

{
  "data": [
    {
      "id": "lp_abc123",
      "name": "Coffee Rewards",
      "qualifying_threshold": 5,
      "reward_config": {
        "type": "refund"
      },
      "display_content": {
        "title": "Buy 5, Get 1 Free",
        "image": "https://cdn.example.com/coffee-card.png",
        "logo": "https://cdn.example.com/logo.png",
        "summary": "Collect 5 stamps and get your next coffee free",
        "description": "Purchase any coffee to earn a stamp...",
        "terms": "Valid at participating locations...",
        "reward": { "formatted": "1 Free Coffee" }
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "page": {
    "page_size": 50,
    "cursor": null,
    "more": false
  }
}

Reward Types

Type	Description	Example
refund	Refund the qualifying purchase amount	Free item
fixed-reward	Fixed cashback amount (in minor units)	{"type": "fixed-reward", "amount": 500} = $5.00 cashback

Display Content

The display_content object provides everything needed to render the loyalty program in your UI:

Field	Description
title	Headline for the program
image	Hero image URL
logo	Brand logo URL (optional)
summary	Short description
description	Full program description
terms	Terms and conditions
reward	Formatted reward description (optional)

Getting a Single Program

{
  "id": "lp_abc123"
}

Enrolling a Member

When a member opts into a loyalty program, create a stamp collection:

curl -X POST https://<your-instance-url>/publisher.v1/wallet.stamp-collection/create \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "loyalty_program_id": "lp_abc123",
    "member_id": "m_x1y2z3"
  }'

A member can only enroll in a given program once. Attempting to create a duplicate stamp collection returns an error.

Checking Progress

Query a stamp collection to see how many qualifying purchases the member has accumulated:

{
  "id": "sc_xyz789"
}

Response:

{
  "id": "sc_xyz789",
  "loyalty_program_id": "lp_abc123",
  "created_at": "2024-01-15T10:30:00Z",
  "unredeemed_purchases": 3
}

The unredeemed_purchases field represents the member's current stamp count. When this reaches the program's qualifying_threshold, the reward is triggered automatically - you do not need to call any additional endpoint.

Listing a Member's Stamp Collections

curl -X POST https://<your-instance-url>/publisher.v1/wallet.stamp-collection/list \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "member_id": "m_x1y2z3",
    "pagination": { "limit": 20 }
  }'

This returns all programs the member is enrolled in, along with their progress.

Integration Pattern

1. Call loyalty-program/list to display available programs
2. Member taps "Join" on a program
3. Call wallet.stamp-collection/create to enroll them
4. Display their stamp collection with current progress
5. As transactions are ingested, stamps accumulate automatically
6. Poll or display stamp-collection/get to show updated progress
7. When threshold is met, a reward webhook is delivered automatically

Important Notes

• Qualifying purchases are determined by the platform based on transaction matching rules configured for the loyalty program. You do not need to manually mark transactions as qualifying.
• After redemption, the unredeemed_purchases counter resets and the member can begin collecting stamps again for the next reward cycle.
• Programs are managed on the K42 platform. Changes to thresholds, rewards, or display content are synced automatically to your Publisher instance.