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.

index

GET /api/v1/accounts/:account_id/rewards

List rewards

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

Code: 200

An array of reward objects

Name Type Required Description
id Must be a Integer Required

Unique reward ID
account_id Must be a Integer Required

Parent store ID
card_id Must be a Integer Required

ID of the loyalty card this reward belongs to
name Must be a String Required

Display name of the reward
description Must be a String Required

Longer description of the reward

(nil allowed)
stamps_required Must be a Integer Required

Stamps needed before the reward can be redeemed
position Must be a Integer Required

Display order

(nil allowed)
active Must be one of: true, false, 1, 0. Required

Whether the reward can currently be redeemed
created_at Must be a String Required

ISO 8601 creation timestamp
updated_at Must be a String Required

ISO 8601 last-update timestamp

show

GET /api/v1/accounts/:account_id/rewards/:id

Show a reward

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

Returns

Code: 200

A reward object

Name Type Required Description
id Must be a Integer Required

Unique reward ID
account_id Must be a Integer Required

Parent store ID
card_id Must be a Integer Required

ID of the loyalty card this reward belongs to
name Must be a String Required

Display name of the reward
description Must be a String Required

Longer description of the reward

(nil allowed)
stamps_required Must be a Integer Required

Stamps needed before the reward can be redeemed
position Must be a Integer Required

Display order

(nil allowed)
active Must be one of: true, false, 1, 0. Required

Whether the reward can currently be redeemed
created_at Must be a String Required

ISO 8601 creation timestamp
updated_at Must be a String Required

ISO 8601 last-update timestamp

create

POST /api/v1/accounts/:account_id/rewards

Create a reward

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

Returns

Code: 201

The newly created reward object

Name Type Required Description
id Must be a Integer Required

Unique reward ID
account_id Must be a Integer Required

Parent store ID
card_id Must be a Integer Required

ID of the loyalty card this reward belongs to
name Must be a String Required

Display name of the reward
description Must be a String Required

Longer description of the reward

(nil allowed)
stamps_required Must be a Integer Required

Stamps needed before the reward can be redeemed
position Must be a Integer Required

Display order

(nil allowed)
active Must be one of: true, false, 1, 0. Required

Whether the reward can currently be redeemed
created_at Must be a String Required

ISO 8601 creation timestamp
updated_at Must be a String Required

ISO 8601 last-update timestamp

update

PATCH /api/v1/accounts/:account_id/rewards/:id

Update a reward

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

Returns

Code: 200

The updated reward object

Name Type Required Description
id Must be a Integer Required

Unique reward ID
account_id Must be a Integer Required

Parent store ID
card_id Must be a Integer Required

ID of the loyalty card this reward belongs to
name Must be a String Required

Display name of the reward
description Must be a String Required

Longer description of the reward

(nil allowed)
stamps_required Must be a Integer Required

Stamps needed before the reward can be redeemed
position Must be a Integer Required

Display order

(nil allowed)
active Must be one of: true, false, 1, 0. Required

Whether the reward can currently be redeemed
created_at Must be a String Required

ISO 8601 creation timestamp
updated_at Must be a String Required

ISO 8601 last-update timestamp

destroy

DELETE /api/v1/accounts/:account_id/rewards/:id

Delete a reward

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

Returns

Code: 204

No content. The reward was deleted.