LoyaltyProgram Resource

Use the LoyaltyProgram resource to access Loyalty Program information.

Resources:

AccrualRule	Duration	ExpirationPolicy	LoyaltyProgram
Money RewardTier	Terminology

Schema type

Use loyalty-program to reference this resource in the template schema.

Querying

You do not need to query for the loyalty program. Including the loyalty program in a template’s schema will give that template access to loyalty program data.

Note that if a loyalty program has not been configured, this resource will throw a 404. Use optional if you want to avoid this behavior.

Currently, including the loyalty-program resource will make the rendered template un-cacheable. Refer to this guide on how to load uncacheable resources with the template API.

Optional

• optional boolean
  • Default: false

  A resource marked as optional will not cause the page to render a 404 view.

    {
        "optional": true
    }
  

Sample Loyalty Program

{
  "__SO_RESOURCE_TYPE__": "loyalty_program", // internally used resource property. do not modify.
  "id": "63524a49-bbdf-4bdc-bb14-ba79dff5c0ce",
  "resource_type": "LOYALTY_PROGRAM",
  "status": "ACTIVE",
  "reward_tiers":
  [
    {
      "id": "eaab89ef-7d65-4eee-82a6-99a1ad25614e",
      "points": 5,
      "name": "A free coffee",
      "discount_scope": "LINE_ITEM",
      "discount_type": "FIXED_PERCENTAGE",
      "percentage": 100.0,
      "maximum_amount_money": null,
      "applicable_item_ids":
      [
        "EOQD2MYJGRUODRNRMPNKHHAZ"
      ]
    },
    {
      "id": "7108f0ad-164b-4ef0-8941-90d99e279780",
      "points": 10,
      "name": "$23.00 off entire sale",
      "discount_scope": "WHOLE_PURCHASE",
      "discount_type": "FIXED_AMOUNT",
      "amount_money":
      {
        "amount": 2300,
        "currency": "CAD",
        "formatted": "$23.00"
      }
    }
  ],
  "terminology":
  {
    "one": "star",
    "other": "stars"
  },
  "location_ids":
  [
    "LRQS655REK0VZ"
  ],
  "accrual_rules":
  [
    {
      "accrual_type": "ITEM_VARIATION",
      "points": 1,
      "item_variation_id": "EOQD2MYJGRUODRNRMPNKHHAZ"
    }
  ],
  "expiration_policy": {
    "expiration_duration": {
      "in_minutes": null,
      "rfc3339_interval": null
    }
  }
}

LoyaltyProgram resources

LoyaltyProgram

A loyalty program.

Field	Type	Description
id	String	Loyalty Program ID
resource_type	String	The resource type identifier
status	String	Whether the program is currently active. Enum: INACTIVE, ACTIVE
reward_tiers	RewardTier[]	The list of rewards for buyers, sorted by ascending points
terminology	Terminology	A cosmetic name for the “points” currency
location_ids	String[]	The locations at which the program is active
accrual_rules	AccrualRule[]	Defines the ways that buyers can earn loyalty points
expiration_policy	ExpirationPolicy	Information about the expiration policy for the program

Back to top

RewardTier

A reward tier defines how buyers can redeem points for a reward, such as the number of points required and the value and scope of the discount. A loyalty program can offer multiple reward tiers.

Field	Type	Description
id	String	The ID of the reward tier
points	Number	The points needed to redeem the reward
name	String	The name of the reward tier
discount_scope	String	Whether the discount applies to the whole order, or certain line items. Enum: WHOLE_PURCHASE, LINE_ITEM
discount_type	String	If the discount is a fixed amount, or a fixed percentage. Enum: FIXED_AMOUNT, FIXED_PERCENTAGE
amount_money	Money	Amount of a FIXED_AMOUNT discount. Only included for FIXED_AMOUNT
percentage	Number	Percentage of a FIXED_PERCENTAGE. Only included for FIXED_PERCENTAGE.
maximum_amount_money	Money	Maximum amount of a FIXED_PERCENTAGE discount. null if there is no maximum
applicable_item_ids	String[]	Item IDs the discount applies to, if the discount is scoped to items (scope will be LINE_ITEM)
applicable_category_ids	String[]	Category IDs the discount applies to, if the discount is scoped to categories (scope will be LINE_ITEM)

Back to top

Terminology

A cosmetic name for the “points” currency.

Field	Type	Description
one	String	A singular unit for a point (for example, 1 point is called 1 star)
other	String	A plural unit for point (for example, 10 points is called 10 stars)

Back to top

AccrualRule

Defines a way that buyers can earn loyalty points

Field	Type	Description
accrual_type	String	The type of the accrual rule that defines how buyers can earn points. Enum: VISIT, SPEND, ITEM_VARIATION, CATEGORY
points	Number	The number of points that buyers earn based on the accrual_type
visit_minimum_amount_money	Money	When the accrual rule is visit-based, this field indicates the minimum purchase required during the visit to quality for the reward
spend_amount_money	Money	When the accrual rule is spend-based, this field indicates the amount that a buyer must spend to earn the points
excluded_item_variation_ids	String[]	When the accrual rule is spend-based, this field lists the IDs of any ITEM_VARIATION catalog objects that are excluded from points accrual
excluded_category_ids	String[]	When the accrual rule is spend-based, this field lists the IDs of any CATEGORY catalog objects that are excluded from points accrual
item_variation_id	String	The ID of the ITEM_VARIATION that buyers can purchase to earn points
category_id	String	The ID of the CATEGORY that buyers can purchase to earn points
tax_mode	String	Indicates how taxes should be treated when calculating the purchase amount used for points accrual

Back to top

Money

Information about monetary amounts.

Field	Type	Description
amount	Number	Amount in the smallest subunit of the given currency
currency	String	The ISO 4217 three-letter currency code
formatted	String	Amount formatted with the symbol of the given currency. Formatted according to the site’s locale

Back to top

Duration

Duration.

Field	Type	Description
in_minutes	Number	Duration in minutes.
rfc3339_interval	String	Duration in RFC3339 format.

Back to top

ExpirationPolicy

Information about the expiration policy.

Field	Type	Description
expiration_duration	Duration	Details about the expiration duration for points. Values are null if there is no expiration.

Back to top