Reward object - Mage Loyalty Documentation

Rewards are configured by the merchant and can be redeemed by customers using their points. Each reward generates a Shopify discount code on redemption.

Attributes

Field	Type	Description
`name`	string	Reward display name
`description`	string \| null	Optional description
`discount_type`	string	Type of discount: `fixed`, `percentage`, `free-shipping`, `free-product`
`reward_type`	string	`loyalty` for a standard reward, or `vip` for a VIP tier reward
`points_cost`	integer	Points required to redeem this reward. Minor currency units in store-credit mode (see Loyalty modes)
`discount_amount`	number	The discount value (e.g. `5.00` for £5 off)
`minimum_spend`	number \| null	Minimum order value required to use the discount
`is_active`	boolean	Whether the reward is currently available
`max_redemptions`	integer \| null	Maximum total redemptions allowed, or `null` for unlimited
`expiry_days`	integer \| null	Number of days the discount code is valid after redemption
`tier_name`	string \| null	The VIP tier this reward is exclusive to, by name. `null` when available to all members
`redemption_mode`	string	`standard` for a fixed redemption, or `flexible` when the customer chooses how many points to spend
`flexible_config`	object \| null	Redemption bounds for `flexible` rewards (see below). `null` for standard rewards
`free_product`	object \| null	The granted product, for `free-product` rewards (see below). `null` for all other reward types
`created_at`	string	ISO 8601 timestamp

Flexible config

For flexible rewards, flexible_config defines the range the customer can redeem. Use it to know the valid points range when calling Purchase a reward.

Field	Type	Description
`min_points`	integer	Minimum amount the customer can redeem (minor units in store-credit mode)
`max_points`	integer	Maximum amount the customer can redeem (minor units in store-credit mode)
`conversion_rate`	number	Cash discount produced per `per_points`. In store-credit mode this is pinned so 1 minor unit of credit equals 1 minor unit of discount
`per_points`	integer	The points unit the `conversion_rate` applies to

Free product details

For free-product rewards, free_product describes the product the customer receives:

Field	Type	Description
`product_name`	string \| null	The product’s name
`product_id`	string \| null	The Shopify product ID
`variant_id`	string \| null	The Shopify variant ID, when a specific variant is granted
`product_amount`	number \| null	Quantity of the product granted

Example

{
  "type": "reward",
  "id": "reward_abc",
  "attributes": {
    "name": "£5 off your next order",
    "description": null,
    "discount_type": "fixed",
    "reward_type": "loyalty",
    "points_cost": 500,
    "discount_amount": 5.00,
    "minimum_spend": 20.00,
    "is_active": true,
    "max_redemptions": null,
    "expiry_days": 30,
    "tier_name": null,
    "redemption_mode": "standard",
    "flexible_config": null,
    "free_product": null,
    "created_at": "2024-01-01T00:00:00.000Z"
  }
}

Flexible reward example

A flexible reward reports redemption_mode: "flexible" and a populated flexible_config:

{
  "type": "reward",
  "id": "reward_flex",
  "attributes": {
    "name": "Spend your points",
    "description": null,
    "discount_type": "fixed",
    "reward_type": "loyalty",
    "points_cost": 100,
    "discount_amount": 1.00,
    "minimum_spend": null,
    "is_active": true,
    "max_redemptions": null,
    "expiry_days": 30,
    "tier_name": null,
    "redemption_mode": "flexible",
    "flexible_config": {
      "min_points": 100,
      "max_points": 5000,
      "conversion_rate": 0.01,
      "per_points": 1
    },
    "free_product": null,
    "created_at": "2024-01-01T00:00:00.000Z"
  }
}