Claimed rewards

A Claimed Reward represents a unique instance of a particular customer having claimed a Reward.

idintegerUnique ID of the claimed reward in LoyaltyLion
claimed_atstringAn ISO 8601 string representing the time the reward was claimed
point_costintegerThe points the customer spent to claim the reward
redeemableobjectThe specific redeemable that was allocated to the customer
rewardobjectThe base reward that was claimed
statestringThe claimed reward state (approved, void)
sessionobject | nullThe session a claimed reward is linked to, only applicable to some rewards (for example, checkout redemption, buy with points)


A Redeemable represents something a customer can redeem to get a benefit - including vouchers and custom reward fulfilments


A Voucher represents a discount voucher which can be applied at checkout.

codestringThe voucher code
discount_amountinteger | nullThe voucher’s discount amount, if different from the associated Reward’s base amount
usage_countintegerThe number of times the voucher has been applied
usage_limitintegerThe number of times the voucher may be applied


A Fulfilment represents the benefit from a custom reward.

fulfilledbooleantrue if the custom reward has been fulfilled
fulfilled_atstring | nullThe ISO 8601 string that the reward was fulfilled

Claimed reward session

A Claimed Reward Session represents the session this claimed reward was claimed in.

kindstringThe kind of session the claimed reward links to, one of custom, cart or checkout
tokenstringThe token associated with the session

POST /v2/customers/:merchant_id/claimed_rewards

Claims a reward, or errors if the customer has insufficient points to claim the reward.


reward_idintegeryesThe ID of the reward the customer is claiming
multiplierintegernoThe multiplier of the reward being claimed. Only supported for custom discount type


On success, the endpoint returns a claimed reward.

If the customer has insufficient points, the endpoint returns a HTTP 422.


curl -X POST \
  --url '' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "reward_id": 123,

POST /v2/customers/:merchant_id/claimed_rewards/:id/refund

Refunds a claimed reward.


There are no parameters for this request.


On success, the endpoint returns the refunded reward and whether the underlying reward resource has been deleted.

claimed_rewardobjectThe claimed reward that was refunded
remote_resource_deletedbooleantrue if the remote resource was deleted, false if it wasn’t
  • Returns a 200 response with the updated reward if the refund was successful.
  • Returns a 422 response if the reward has already been refunded.
  • If no customer matching the :merchant_id can be found, then a 404 Not Found response is returned.
  • If no reward matching the :id can be found, then a 404 Not Found response is returned.


curl -X POST \
  --url '' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json'