Claimed rewards

Rewards API is currently in beta testing and available to our Tech Partners. If you’d like to get it enabled for your store, contact us at and include your specific use case.

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)
expires_atstring | nullAn ISO 8601 string representing when the claimed reward will expire, or null if it does not expire


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

Free product

A Free Product represents a free product which can be claimed at checkout

redeemable_typestringAlways ‘product’
productobjectThe product id and variant id that’s being redeemed
used_atstring | nullAn ISO 8601 timestamp representing when this reward was used
shopify_cart_line_item_contextstringThe encrypted secret which discounts the line item to free during checkout


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 reward type
variant_idintegersometimesThe Shopify variant being claimed. Required when the reward is a seamless product reward


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 '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 'Content-Type: application/json'