Points API
Award points, check balances, and retrieve transaction history.
Points API
The Points API allows you to manage point balances and transactions for your program members.
Get Balance
Retrieve a member's current points balance.
GET /v1/members/{member_id}/balance
Example Response
{
"success": true,
"data": {
"member_id": "mem_abc123",
"balance": 5000,
"lifetime_earned": 12500,
"lifetime_redeemed": 7500,
"pending": 500
}
}
Award Points
Add points to a member's balance.
POST /v1/points/award
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
member_id | string | Yes | The member to award points to |
points | integer | Yes | Number of points to award |
reason | string | Yes | Description of why points were awarded |
reference | string | No | External reference (e.g., invoice number) |
metadata | object | No | Additional data to store with transaction |
Example Request
curl -X POST "https://api.incentable.com/v1/points/award" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"member_id": "mem_abc123",
"points": 500,
"reason": "Q2 Sales Target Achievement",
"reference": "INV-2024-1234",
"metadata": {
"campaign": "q2-sales-push",
"product_category": "Electronics"
}
}'
Example Response
{
"success": true,
"data": {
"transaction_id": "txn_def456",
"member_id": "mem_abc123",
"points": 500,
"type": "award",
"reason": "Q2 Sales Target Achievement",
"new_balance": 5500,
"created_at": "2024-06-15T14:30:00Z"
}
}
Bulk Award Points
Award points to multiple members in a single request.
POST /v1/points/award/bulk
Request Body
{
"awards": [
{
"member_id": "mem_abc123",
"points": 500,
"reason": "Monthly bonus"
},
{
"member_id": "mem_xyz789",
"points": 750,
"reason": "Monthly bonus"
}
]
}
Example Response
{
"success": true,
"data": {
"processed": 2,
"failed": 0,
"transactions": [
{ "member_id": "mem_abc123", "transaction_id": "txn_001" },
{ "member_id": "mem_xyz789", "transaction_id": "txn_002" }
]
}
}
Deduct Points
Remove points from a member's balance (e.g., for adjustments).
POST /v1/points/deduct
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
member_id | string | Yes | The member to deduct points from |
points | integer | Yes | Number of points to deduct |
reason | string | Yes | Description of why points were deducted |
For reward redemptions, use the Rewards API instead. This endpoint is for manual adjustments only.
Transaction History
Retrieve a member's point transaction history.
GET /v1/members/{member_id}/transactions
Query Parameters
| Parameter | Type | Description |
|---|---|---|
page | integer | Page number |
per_page | integer | Results per page (max: 100) |
type | string | Filter by type: award, redeem, deduct, expire |
from | string | Start date (ISO 8601) |
to | string | End date (ISO 8601) |
Example Response
{
"success": true,
"data": [
{
"transaction_id": "txn_def456",
"type": "award",
"points": 500,
"reason": "Q2 Sales Target Achievement",
"balance_after": 5500,
"created_at": "2024-06-15T14:30:00Z"
},
{
"transaction_id": "txn_abc123",
"type": "redeem",
"points": -1000,
"reason": "Amazon Gift Card $10",
"balance_after": 5000,
"created_at": "2024-06-10T09:15:00Z"
}
]
}