Claim API - Loyalty
Endpoints for managing reward claim requests - creating, approving, and rejecting redemptions for the Loyalty API.
/api/v1/loyalty/claims/
Complete Claim Flow
Here's the typical flow for processing a reward redemption:
Member Initiates Claim
Member selects a reward and confirms they want to redeem their points.
Request OTP
Call /claims/request-otp to send verification to member's email.
Create Claim Request
Submit the claim with the OTP code via /claims.
Staff Approves/Rejects
Staff reviews and processes the claim via approve or reject endpoints.
Request Claim OTP
/api/v1/loyalty/claims/request-otp
Request a verification code for claiming a reward. OTP is sent to member's email.
Request Body
{
"member_email": "ahmed@example.com",
"card_id": 5,
"reward_id": 1
}
member_email (string, required) - Member's email
card_id (integer, required) - Card ID
reward_id (integer, optional) - Reward ID
Response
{
"success": true,
"data": {
"expires_at": "2025-01-15T10:40:00Z",
"expires_in_minutes": 10
},
"message": "Verification code sent to member email."
}Create Claim Request
/api/v1/loyalty/claims
Create a new reward claim request. OTP verification required.
Request Body
{
"member_email": "ahmed@example.com",
"card_id": 5,
"reward_id": 1,
"verification_code": "123456",
"member_note": "Pickup at downtown branch"
}
member_email (string, required) - Member's email
card_id (integer, required) - Card ID
reward_id (integer, required) - Reward ID
verification_code (string, required) - 6-digit OTP code
member_note (string, optional) - Member note
Response
{
"success": true,
"data": {
"claim_request": {
"id": 100,
"status": "pending",
"created_at": "2025-01-15T10:30:00Z"
}
}
}List Claim Requests
/api/v1/loyalty/claims?card_id={card_id}&status={status}
Get all claim requests for a card, optionally filtered by status.
Query Parameters
card_id=5
status=pending
card_id (integer, required) - The card ID
status (string, optional) - Filter: pending, approved, rejected, expired
Get Claim Request
/api/v1/loyalty/claims/{request_id}
Get details of a specific claim request.
URL Parameter: request_id (integer, required) - The request ID
Approve Claim Request
/api/v1/loyalty/claims/{request_id}/approve
Approve a pending claim request and process the reward. Points are deducted from member's balance.
Request Body
{
"staff_note": "Approved via API"
}staff_note (string, optional) - Staff note
Response
{
"success": true,
"data": {
"claim_request": {
"id": 100,
"status": "approved",
"points_deducted": 500,
"approved_at": "2025-01-15T11:00:00Z"
}
}
}Reject Claim Request
/api/v1/loyalty/claims/{request_id}/reject
Reject a pending claim request. Points remain with the member.
Request Body
{
"staff_note": "Insufficient points balance"
}staff_note (string, optional) - Staff note
Response
{
"success": true,
"data": {
"claim_request": {
"id": 100,
"status": "rejected",
"rejected_at": "2025-01-15T11:00:00Z"
}
}
}