Rewards

A Reward resource represents something that customers may spend their points on.

FieldTypeDescription
idintegerUnique ID of the reward in LoyaltyLion
kindstringThe kind of reward
titlestringThe display title of the reward, in your site’s primary language
descriptionstring | nullOptional extra reward description
contentobjectAdditional content that’s needed when working with or rendering the reward. This may include things like image urls, fulfilment_instructions, or other strings you may want to render or utilize in some way
point_costintegerThe cost of redeeming the reward in points
methodstringHow the reward is redeemed; one of voucher, store_fulfilment or gift_card
discount_typestringThe monetary effect of the discount. One of flat (reduce target price by discount_amount currency units), percentage (reduce target price by discount_amount percent), custom (implementation-defined)
discount_amountinteger | nullWhen the reward has a specific monetary or percentage value, that value as a unit-less number. So if the discount amount is £5 or 5%, this returns 5
minimum_spendinteger | nullThe amount a customer must spend to be able to use the reward. A minimum_spend of 30 returns 30
usage_limitintegerThe number of times the reward may be used once claimed, typically 1
min_redemption_amountintegerThe minimum multiplier of the reward that can be claimed at once
max_redemption_amountintegerThe maximum multiplier of the reward that can be claimed at once
max_free_shippinginteger | nullThe maximum amount that can be deducted from shipping by a free shipping reward. If null then there is no limit
site_idintegerThe site ID the reward is associated with
target_siteobjectA reward site object (see below). Provides the details about the site where a reward may be used
order_typestringWhat orders the reward applies to; one of all, one_time or subscription
target_typestringWhat the reward applies to; one of all, collection, custom, product or shipping
target_collectionsarrayAn array of target collection objects (see below)
target_productsarrayAn array of target product objects (see below)
session_optionsobject | nullA reward session options object (see below)

Reward site object

FieldTypeDescription
idintegerThe ID of the target site
namestringThe name of the target site
urlstringThe URL linking to the target site

Target collection object

FieldTypeDescription
idintegerThe ID of the target collection
urlstringThe URL linking to the target collection
restriction_textstringText shown when the reward isn’t usable due to items not being in the correct collection

Target product object

FieldTypeDescription
idintegerThe ID of the target product
variant_idintegerThe variant ID of the target product
skustringThe SKU of the target product
urlstringThe URL linking to the target product
image_urlstringThe URL linking to the image of the target product
sort_keyintegerThe key used to sort the target product
titlestringThe title of the target product

Reward session options object

FieldTypeDescription
kindstringThe kind of session the reward links to, one of custom, cart or checkout
session_limitinteger | nullThe number of times the reward may be claimed in one session, typically 1

Claimed reward object

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

Voucher object

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

Fulfilment object

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

Claimed reward session object

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

GET /v2/customers/:merchant_id/available_rewards

The endpoint is in beta. Contact support to request access.

Returns a list of all rewards that the customer is permitted to claim, including ones not currently affordable.

The :merchant_id provided should match your own internal ID for the customer in your database.

Request

This request takes no parameters.

Response

The endpoint returns a list of reward resources.

Example

curl -X GET \
  --url 'https://api.loyaltylion.com/v2/customers/1001/available_rewards' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json'

POST /v2/customers/:merchant_id/claimed_rewards

The endpoint is in beta. Contact support to request access.

Claims a reward, or an error 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 discount type

Response

On success, the endpoint returns a claimed reward resource.

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 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "reward_id": 123,
  }'

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

The endpoint is in beta. Contact support to request access.

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 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 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json'