Rewards API
Manage your rewards catalog and process member redemptions.
Rewards API
The Rewards API allows you to manage your rewards catalog and handle member redemptions.
List Rewards
Retrieve all available rewards in your catalog.
GET /v1/rewards
Query Parameters
| Parameter | Type | Description |
|---|---|---|
page | integer | Page number |
per_page | integer | Results per page |
category | string | Filter by category |
status | string | Filter by status: active, inactive |
min_points | integer | Minimum point value |
max_points | integer | Maximum point value |
Example Response
{
"success": true,
"data": [
{
"id": "rwd_001",
"name": "Amazon Gift Card $25",
"description": "Digital Amazon.com gift card",
"points_cost": 2500,
"category": "Gift Cards",
"type": "digital",
"status": "active",
"image_url": "https://cdn.incentable.com/rewards/amazon-25.png",
"stock": null
},
{
"id": "rwd_002",
"name": "Wireless Earbuds",
"description": "Premium wireless earbuds with charging case",
"points_cost": 15000,
"category": "Electronics",
"type": "physical",
"status": "active",
"image_url": "https://cdn.incentable.com/rewards/earbuds.png",
"stock": 50
}
]
}
Get Reward
Retrieve details for a specific reward.
GET /v1/rewards/{reward_id}
Redeem Reward
Process a reward redemption for a member.
POST /v1/rewards/redeem
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
member_id | string | Yes | The member redeeming the reward |
reward_id | string | Yes | The reward being redeemed |
quantity | integer | No | Number of items (default: 1) |
shipping_address | object | Conditional | Required for physical rewards |
Example Request (Digital Reward)
curl -X POST "https://api.incentable.com/v1/rewards/redeem" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"member_id": "mem_abc123",
"reward_id": "rwd_001"
}'
Example Request (Physical Reward)
curl -X POST "https://api.incentable.com/v1/rewards/redeem" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"member_id": "mem_abc123",
"reward_id": "rwd_002",
"shipping_address": {
"name": "John Smith",
"line1": "123 Main Street",
"line2": "Suite 100",
"city": "New York",
"state": "NY",
"postal_code": "10001",
"country": "US"
}
}'
Example Response
{
"success": true,
"data": {
"order_id": "ord_789xyz",
"member_id": "mem_abc123",
"reward_id": "rwd_001",
"reward_name": "Amazon Gift Card $25",
"points_spent": 2500,
"status": "completed",
"fulfillment": {
"type": "digital",
"code": "AMZN-XXXX-XXXX-XXXX",
"delivered_at": "2024-06-15T14:35:00Z"
},
"new_balance": 2500
}
}
List Orders
Retrieve redemption orders for tracking and fulfillment.
GET /v1/orders
Query Parameters
| Parameter | Type | Description |
|---|---|---|
status | string | Filter: pending, processing, shipped, completed, cancelled |
member_id | string | Filter by member |
from | string | Start date |
to | string | End date |
Example Response
{
"success": true,
"data": [
{
"order_id": "ord_789xyz",
"member_id": "mem_abc123",
"reward_name": "Wireless Earbuds",
"points_spent": 15000,
"status": "shipped",
"tracking_number": "1Z999AA10123456784",
"carrier": "UPS",
"created_at": "2024-06-10T09:00:00Z",
"shipped_at": "2024-06-12T14:00:00Z"
}
]
}
Update Order Status
Update the fulfillment status of an order.
PATCH /v1/orders/{order_id}
Request Body
{
"status": "shipped",
"tracking_number": "1Z999AA10123456784",
"carrier": "UPS"
}