🔄 Loyalty API Workflows

Step-by-step integration guides for common POS scenarios

1. Member Check & Earn Points (Checkout Flow)

Complete checkout workflow: Lookup member (or register), calculate points, and earn.

Lookup → Register? → Calculate → Earn Points

Step 1: Lookup Member (Enriched)

Use the enriched lookup endpoint to get customer profile, transactions, and available vouchers in a single call.

GET /api/loyalty/customers/lookup-enriched

Request Parameters:

Parameter Type Required Description
phone string Conditional* Phone number with country code (e.g., +60123456789)
identifier string Conditional* QR code or promo code
include string Optional Comma-separated: transactions, vouchers, wallet_stats

*Either phone or identifier must be provided

Example Request:

curl -X GET "https://kirimel.com/api/loyalty/customers/lookup-enriched?phone=%2B60123456789&include=transactions,vouchers,wallet_stats" \
  -H "X-Client-Key: your_client_key" \
  -H "X-Timestamp: 2026-05-10T14:30:00Z" \
  -H "X-Signature: computed_signature"

Response (Customer Found):

{
  "success": true,
  "data": {
    "customer": {
      "id": 123,
      "phone": "+60123456789",
      "name": "John Doe",
      "email": "[email protected]",
      "status": "ACTIVE"
    },
    "wallet": {
      "balance_points": 1500,
      "total_earned": 5000,
      "total_redeemed": 3500
    },
    "recent_transactions": [
      {
        "transaction_type": "EARN",
        "points_delta": 50,
        "balance_after": 1550,
        "reference": "TXN20260510001",
        "created_at": "2026-05-10T14:30:00Z"
      }
    ],
    "available_vouchers": [
      {
        "id": 456,
        "code": "VOUCHER_A1B2C3",
        "batch_name": "Grand Opening Promo",
        "voucher_type": "PERCENT",
        "voucher_value": 10,
        "valid_until": "2026-12-31",
        "min_purchase": 50.00
      }
    ]
  }
}

Step 1B: Register New Member (if not found)

POST /api/loyalty/customers/register

💡 Phone Format Tip

Use E.164 format: +60123456789 for Malaysia, +6598765432 for Singapore

Step 2: Earn Points

Calculate points using formula: floor(purchase_amount × points_multiplier)

POST /api/loyalty/points/earn 
{
  "customer_id": 123,
  "points": 50,
  "reference_type": "TRANSACTION",
  "reference_id": "TXN20260510001",
  "notes": "Purchase at Checkout Counter 1"
}

2. Points Checking

Quick balance check and tier status.

GET /api/loyalty/wallet/balance

Request Parameters:

Parameter Type Required Description
customer_id integer Required Customer ID 
curl -X GET "https://kirimel.com/api/loyalty/wallet/balance?customer_id=123" \
  -H "X-Client-Key: your_client_key" \
  -H "X-Timestamp: 2026-05-10T14:30:00Z" \
  -H "X-Signature: computed_signature"

Response:

{
  "success": true,
  "data": {
    "customer_id": 123,
    "balance_points": 1500,
    "tier": "SILVER",
    "points_expiring_soon": 100,
    "expiry_date": "2026-06-30"
  }
}

3. Voucher Redemption

Validate and redeem customer vouchers at checkout.

Lookup Voucher → Validate → Redeem

Step 1: Lookup Voucher

GET /api/loyalty/vouchers/lookup 
curl -X GET "https://kirimel.com/api/loyalty/vouchers/lookup?code=VOUCHER_A1B2C3D4E5F6" \
  -H "X-Client-Key: your_client_key" \
  -H "X-Timestamp: 2026-05-10T14:30:00Z" \
  -H "X-Signature: computed_signature"

Step 2: Redeem Voucher

POST /api/loyalty/vouchers/redeem 
{
  "code": "VOUCHER_A1B2C3D4E5F6",
  "customer_id": 123,
  "redemption_type": "PERCENT",
  "redemption_value": 10.00,
  "notes": "Used at Checkout Counter 1"
}

Error Codes:

VOUCHER_EXPIRED
Voucher past expiry date
VOUCHER_ALREADY_REDEEMED
Already used
BELOW_MIN_PURCHASE
Below minimum required

4. Points Payment (Redeem for Payment)

Customer pays using points instead of cash.

Preview → Confirm → Commit

Step 1: Preview Redemption

POST /api/loyalty/points/preview-redeem 
{
  "customer_id": 123,
  "amount": 50.00,
  "requested_points": 500
}

Step 2: Commit Redemption

POST /api/loyalty/points/commit-redeem 
{
  "customer_id": 123,
  "points": 500,
  "reference_type": "TRANSACTION",
  "reference_id": "TXN20260510002",
  "notes": "Paid with points"
}

5. Transaction Void / Refund

Reverse points when customer returns items.

POST /api/loyalty/points/reverse 
{
  "original_reference_type": "TRANSACTION",
  "original_reference_id": "TXN20260510001",
  "notes": "Return - Item defective"
}

6. Get Customer Available Vouchers

Fetch all unused vouchers for a customer.

GET /api/loyalty/customers/{id}/vouchers

Request Parameters:

Parameter Type Required Description
id integer Required Customer ID from URL path 
curl -X GET "https://kirimel.com/api/loyalty/customers/123/vouchers" \
  -H "X-Client-Key: your_client_key" \
  -H "X-Timestamp: 2026-05-10T14:30:00Z" \
  -H "X-Signature: computed_signature"

Response:

{
  "success": true,
  "data": {
    "customer_id": 123,
    "available_vouchers": [
      {
        "id": 456,
        "code": "VOUCHER_A1B2C3",
        "batch_name": "Grand Opening Promo",
        "voucher_type": "PERCENT",
        "voucher_value": 10,
        "valid_until": "2026-12-31",
        "min_purchase": 50.00
      }
    ],
    "count": 1
  }
}

Quick Reference: All Endpoints

Endpoint Method Purpose
/api/loyalty/customers/register POST Register new member
/api/loyalty/customers/lookup-enriched GET Lookup with details ✨
/api/loyalty/customers/lookup-by-email-enriched GET Lookup by email ✨
/api/loyalty/customers/{id}/vouchers GET Get available vouchers ✨
/api/loyalty/points/earn POST Earn points
/api/loyalty/wallet/balance GET Check balance
/api/loyalty/vouchers/lookup GET Validate voucher
/api/loyalty/vouchers/redeem POST Redeem voucher
/api/loyalty/points/preview-redeem POST Preview points payment
/api/loyalty/points/commit-redeem POST Commit points payment
/api/loyalty/points/reverse POST Void transaction

✨ = New enriched endpoints returning full customer data

← Back to API Reference