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 support@loyaltylion.com and include your specific use case.

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

FieldTypeDescription
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

 Redeemables

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

Voucher

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

FieldTypeDescription
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

FieldTypeDescription
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

Fulfilment

A Fulfilment represents the benefit from a custom reward.

FieldTypeDescription
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.

FieldTypeDescription
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.

Request

ParamTypeRequiredDescription
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

Response

On success, the endpoint returns a claimed reward.

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

Example

curl -X POST \
  --url 'https://api.loyaltylion.com/v2/customers/1001/claimed_rewards' \
  --header 'Content-Type: application/json' \
  --data '{
    "reward_id": 123,
  }'

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

Refunds a claimed reward.

Request

There are no parameters for this request.

Response

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

FieldTypeDescription
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.

Example

curl -X POST \
  --url 'https://api.loyaltylion.com/v2/customers/1001/claimed_rewards/123/refund' \
  --header 'Content-Type: application/json'