Points API - Loyalty
Endpoints to earn, redeem and manage loyalty points for the Loyalty API.
/api/v1/loyalty/points/
Earn Points
/api/v1/loyalty/points/earn
Award points to a member based on purchase amount. Supports identification by member_id, email, or phone. Auto-creates members if needed.
How It Works
Card Configuration
The points card has a configured points ratio (e.g., 1 point per $10 spent).
Send Transaction
Send card_id, member identifier and purchase_amount to calculate points.
Credit Points
Points are automatically credited to the member's balance.
Request Body
{
"card_id": 10,
"member_id": 123,
"purchase_amount": 50.00,
"reference": "ORDER-12345"
}
card_id (integer, required) - Points card ID
member_id (integer, conditional) - Member ID
email (string, conditional) - Member email (alternative to member_id)
phone (string, conditional) - Member phone (alternative to member_id)
member_name (string, optional) - Name for member auto-creation
purchase_amount (number, required) - Purchase amount
reference (string, optional) - External transaction reference
Response
{
"success": true,
"data": {
"transaction_id": 456,
"points_earned": 50,
"new_balance": 150,
"member_id": 123,
"card_id": 10,
"is_new_member": false,
"notification_sent": "points_earned",
"reference": "ORDER-12345",
"earned_at": "2025-01-15T10:30:00Z"
}
}Redeem Points
/api/v1/loyalty/points/redeem
Redeem points for a reward. Member must have enough points for the requested reward.
X-Member-Token header to protect member points.
Headers
X-App-Id: app_abc123...
X-Api-Key: test_xyz789...
X-Member-Token: eyJ0eXAiOiJKV1QiLCJhbGc...Request Body
{
"card_id": 10,
"reward_id": 5,
"reference": "REDEEM-12345"
}
card_id (integer, required) - Points card ID
reward_id (integer, required) - Reward ID to redeem
reference (string, optional) - External reference
Response
{
"success": true,
"data": {
"transaction_id": 457,
"reward_id": 5,
"reward_name": "Free Coffee",
"points_redeemed": 100,
"new_balance": 50,
"member_id": 123,
"card_id": 10,
"reference": "REDEEM-12345",
"redeemed_at": "2025-01-15T11:00:00Z"
}
}Refund Points
/api/v1/loyalty/points/refund
Reverse/deduct points previously earned on a purchase. Use when an order is refunded to remove the corresponding points.
Request Body
{
"card_id": 10,
"member_id": 123,
"refund_amount": 25.00,
"reference": "REFUND-ORDER-12345"
}
card_id (integer, required) - Points card ID
member_id (integer, conditional) - Member ID
email (string, conditional) - Member email (alternative to member_id)
phone (string, conditional) - Member phone (alternative to member_id)
refund_amount (number, required) - Refund amount
points_to_deduct (integer, optional) - Explicit points to deduct
reference (string, optional) - Transaction reference
Response
{
"success": true,
"data": {
"transaction_id": 458,
"points_deducted": 25,
"refund_amount": 25.00,
"previous_balance": 150,
"new_balance": 125,
"member_id": 123,
"card_id": 10,
"reference": "REFUND-ORDER-12345",
"balance_warning": null,
"refunded_at": "2025-01-15T12:00:00Z"
}
}Points Balance
/api/v1/loyalty/points/balance
Retrieve member's current points balance on a specific card.
Query Parameters
GET /api/v1/loyalty/points/balance?card_id=10&member_id=123
card_id (integer, required) - Points card ID
member_id (integer, required) - Member ID
Response
{
"success": true,
"data": {
"card_id": 10,
"member_id": 123,
"points_balance": 150,
"reward_system": "points",
"queried_at": "2025-01-15T10:30:00Z"
}
}Points History
/api/v1/loyalty/points/history
Retrieve member's points transaction history with pagination.
Query Parameters
GET /api/v1/loyalty/points/history?card_id=10&member_id=123&limit=20&offset=0
card_id (integer, required) - Card ID
member_id (integer, required) - Member ID
limit (integer, optional) - Number of results (default: 20, max: 100)
offset (integer, optional) - Offset for pagination
Response
{
"success": true,
"data": {
"card_id": 10,
"member_id": 123,
"transactions": [
{
"id": 456,
"points": 50,
"event": "staff_added_points",
"created_at": "2025-01-15T10:30:00Z"
},
{
"id": 457,
"points": -100,
"event": "staff_redeemed_reward",
"created_at": "2025-01-15T11:00:00Z"
}
],
"pagination": {
"limit": 20,
"offset": 0,
"total": 45,
"has_more": true
}
}
}