Rewards
Manage loyalty card rewards
Rewards are redeemable milestones tied to a loyalty card. When a customer reaches the required number of stamps, they become eligible to redeem the reward. Each reward belongs to a specific card.
Returns all rewards for the store. Optionally filter by card or active status.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
account_id
|
Must be a number. | Required |
Store (account) ID |
card_id
|
Must be a number. | Optional |
Filter rewards belonging to a specific card |
active
|
Must be a String | Optional |
When present, return only active rewards |
Error Codes
| Code | Description |
|---|---|
401
|
Unauthorized – invalid or missing API token |
404
|
Store not found |
Returns a single reward by ID.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
account_id
|
Must be a number. | Required |
Store (account) ID |
id
|
Must be a number. | Required |
Reward ID |
Error Codes
| Code | Description |
|---|---|
401
|
Unauthorized – invalid or missing API token |
404
|
Store or reward not found |
Creates a new reward for a loyalty card. The card must belong to the same store. The card_id is required on create but cannot be changed afterwards.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
account_id
|
Must be a number. | Required |
Store (account) ID |
reward
|
Must be a Hash | Required |
Reward attributes |
reward[card_id]
|
Must be a number. | Required |
ID of the loyalty card this reward belongs to |
reward[name]
|
Must be a String | Required |
Display name of the reward (e.g. ‘Free Coffee’) |
reward[description]
|
Must be a String | Optional |
Detailed description of the reward |
reward[stamps_required]
|
Must be a number. | Required |
Number of stamps needed to unlock this reward (must be > 0) |
reward[position]
|
Must be a number. | Optional |
Display order position (lower numbers appear first) |
reward[active]
|
Must be one of: true, false, 1, 0.
|
Optional |
Whether the reward is active and redeemable (defaults to true) |
Error Codes
| Code | Description |
|---|---|
401
|
Unauthorized – invalid or missing API token |
404
|
Store or card not found |
422
|
Validation failed – check `errors` for details |
Updates an existing reward. The card_id cannot be changed after creation.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
account_id
|
Must be a number. | Required |
Store (account) ID |
id
|
Must be a number. | Required |
Reward ID |
reward
|
Must be a Hash | Required |
Reward attributes to update |
reward[name]
|
Must be a String | Optional |
Display name of the reward |
reward[description]
|
Must be a String | Optional |
Detailed description of the reward |
reward[stamps_required]
|
Must be a number. | Optional |
Number of stamps needed to unlock this reward (must be > 0) |
reward[position]
|
Must be a number. | Optional |
Display order position |
reward[active]
|
Must be one of: true, false, 1, 0.
|
Optional |
Whether the reward is active and redeemable |
Error Codes
| Code | Description |
|---|---|
401
|
Unauthorized – invalid or missing API token |
404
|
Store or reward not found |
422
|
Validation failed – check `errors` for details |
Permanently deletes a reward. This cannot be undone.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
account_id
|
Must be a number. | Required |
Store (account) ID |
id
|
Must be a number. | Required |
Reward ID |
Error Codes
| Code | Description |
|---|---|
401
|
Unauthorized – invalid or missing API token |
404
|
Store or reward not found |
422
|
Reward could not be deleted |