Rewards
A Reward resource represents something that customers may spend their points on.
| Field | Type | Description |
|---|---|---|
id | integer | Unique ID of the reward in LoyaltyLion |
kind | string | The kind of reward |
title | string | The display title of the reward, in your site’s primary language |
description | string or null | Optional extra reward description |
content | object | Additional 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_cost | integer | The cost of redeeming the reward in points |
method | string | How the reward is redeemed; one of voucher, store_fulfilment or gift_card |
discount_type | string | The 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_amount | integer or null | When 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_spend | integer or null | The amount a customer must spend to be able to use the reward. A minimum_spend of 30 returns 30 |
usage_limit | integer | The number of times the reward may be used once claimed, typically 1 |
min_redemption_amount | integer | The minimum multiplier of the reward that can be claimed at once |
max_redemption_amount | integer | The maximum multiplier of the reward that can be claimed at once |
max_free_shipping | integer or null | The maximum amount that can be deducted from shipping by a free shipping reward. If null then there is no limit |
site_id | integer | The site ID the reward is associated with |
sort_key | integer | 1-based position of the reward in the loyalty program’s list of rewards |
target_site | object | A reward site describing where a reward may be used |
order_type | string | What orders the reward applies to; one of all, one_time or subscription |
target_type | string | What the reward applies to; one of all, collection, custom, product or shipping |
target_collections | array | An array of target collections |
target_products | array | An array of target products |
session_options | object or null | A reward session options object (see below) |
auto_refund_seconds | integer or null | Duration in seconds after which this reward will be voided and refunded if it has not been used |
redeemable_expiry_options | object or null | A redeemable expiry options object (see below), indicating the conditions in which the redeemable attached to this claimed reward will be expired. If null, the redeemable does not expire |
expiry_options | object | DEPRECATED A reward expiry options object, replaced by auto_refund_seconds |
Reward site
A Site indicates the site (ecommerce store, POS location, blog) that this reward is usable on.
If the id field doesn’t match the parent reward.site_id, that indicates that this is a cross-store reward.
| Field | Type | Description |
|---|---|---|
id | integer | The ID of the target site |
name | string | The name of the target site |
url | string | The URL linking to the target site |
Target collection
A Target Collection represents a product collection that this reward is applicable to.
| Field | Type | Description |
|---|---|---|
id | integer | The ID of the target collection |
url | string | The URL linking to the target collection |
restriction_text | string | Text shown when the reward isn’t usable due to items not being in the correct collection |
Target product
A Target Product represents a product that this reward is applicable to.
| Field | Type | Description |
|---|---|---|
id | integer | The ID of the target product |
variant_id | integer | The variant ID of the target product |
sku | string | The SKU of the target product |
url | string | The URL linking to the target product |
image_url | string | The URL linking to the image of the target product |
sort_key | integer | The key used to sort the target product |
title | string | The title of the target product |
Reward session options
Session options, when present, describe any limits on how many of this reward may be claimed within a particular checkout session.
When null, the reward has no claim limit per session (though it may still have an overall usage limit).
| Field | Type | Description |
|---|---|---|
kind | string | The kind of session the reward links to, one of custom, cart or checkout |
session_limit | integer or null | The number of times the reward should be claimed in one session, typically 1. Please note, this limit is not enforced by LoyaltyLion. Enforcing this limit is the responsibility of the API consumer. |
Reward expiry options
Expiry options describe how the reward will expire. Rewards that do not expire are
denoted by kind does_not_expire.
| Field | Type | Description |
|---|---|---|
kind | string | The kind of expiry option for the reward, one of does_not_expire or duration |
seconds | number or null | The number of seconds, after being claimed, that the reward will expire |
GET /v2/customers/:merchant_id/available_rewards
Returns a list of the rewards currently available to this customer.
Rewards are available to a customer for the purposes of this API if:
- The reward is enabled
- If a customer is in a loyalty tier, the reward is available on that tier
- The reward is supported based on your platform
For seamless product rewards, these additional conditions apply:
- Instant points are not enabled
- Shopify scripts are in use
The free shipping reward is currently unsupported on this endpoint.
| Platform | Supported rewards |
|---|---|
| Shopify | one-off discount rewards (e.g $5 off, 10% off, including new subscription rewards), custom rewards, checkout rewards, free product vouchers, seamless free products |
| Adobe Commerce (formerly Magento) | one-off discount rewards, custom rewards, free product vouchers |
| BigCommerce | one-off discount rewards, custom rewards, free product vouchers |
| Custom | custom rewards |
Available rewards include those that cost more points than the customer currently has available.
The :merchant_id provided should match your own internal ID (from your ecommerce platform) for the customer in your database.
If you have a multi-site program, this endpoint returns rewards for all sites in your program. To filter to a single site, pass a site_id filter param.
Request
You can pass the following optional query parameters with the request.
| Param | Description |
|---|---|
site_id | Return only rewards for this site |
Response
The endpoint returns a list of rewards.
Example
curl -X GET \
--url 'https://api.loyaltylion.com/v2/customers/1001/available_rewards' \
--header 'Content-Type: application/json'