Developer Reference

Metafields Reference

Easy Pointly stores loyalty data in Shopify metafields so you can display points, tiers, and rewards anywhere in your theme using Liquid — no custom API calls required. All customer metafields are set to PUBLIC_READ storefrontAccess.

Customer metafields

Per-customer loyalty data

These metafields are written to each customer record as their loyalty activity changes. Use them in Liquid wherever customer is available.

namespace: easy-pointly-loyalty

Key	Type	Description	Liquid
points	integer	Current spendable points balance	`customer.metafields["easy-pointly-loyalty"]["points"].value`
lifetime_points	integer	Total points ever earned — used to determine tier	`customer.metafields["easy-pointly-loyalty"]["lifetime_points"].value`
tier_index	integer	Tier level 1–5 (1 = base tier, 5 = highest)	`customer.metafields["easy-pointly-loyalty"]["tier_index"].value`
tier_name	string	Human-readable tier label (e.g. 'Gold')	`customer.metafields["easy-pointly-loyalty"]["tier_name"].value`
history_json	json	Array of recent point transactions	`customer.metafields["easy-pointly-loyalty"]["history_json"].value`
opted_in	boolean	Whether the customer has enrolled in the program	`customer.metafields["easy-pointly-loyalty"]["opted_in"].value`

LIQUID EXAMPLE — points balance widgetLiquid

{%- assign lp = customer.metafields["easy-pointly-loyalty"] -%}
{%- if lp.opted_in.value -%}
  <p>Your balance: <strong>{{ lp.points.value }} pts</strong></p>
  <p>Tier: {{ lp.tier_name.value }}</p>
{%- else -%}
  <p>Join our loyalty program to start earning points.</p>
{%- endif -%}

Shop metafield

Program settings & tier thresholds

One JSON metafield on the shop resource holds your program configuration. Read it to display tier requirements, earn rates, and feature flags in your theme.

namespace: easy-pointly-loyalty·key: settings

Tier names & thresholds (compare against customer lifetime_points)

t1Name

Tier 1 label (base tier — 0 lifetime pts required)

t2Name / t2Min / t2Active

Tier 2 label, minimum lifetime points required, and whether this tier is enabled

t3Name / t3Min / t3Active

Tier 3 (same pattern as t2)

t4Name / t4Min / t4Active

Tier 4

t5Name / t5Min / t5Active

Tier 5 (highest)

Earn & redeem rates

pointsPerDollar

Points earned per $1 spent. Value = points ÷ pointsPerDollar

minPointsToRedeem

Minimum balance before a customer can redeem

Feature flags (pre-computed — do not re-derive from plan string)

referralVisible

Boolean — show referral section in theme

referralPoints

Points awarded for a successful referral

birthdayBonusEnabled

Boolean — show birthday DOB field in theme

birthdayBonusPoints

Points awarded on birthday

judgemeVisible

Boolean — show Judge.me review perk

judgemeReviewPoints

Points for an approved review

judgemePhotoBonus

Extra points for a photo review (0 if disabled)

freeShippingVisible

Boolean — show free-shipping perk

freeShippingTier

Tier index (1–5) that unlocks free shipping

freeShippingMinCart

Minimum cart value to trigger free shipping

LIQUID EXAMPLE — tier progress barLiquid

{%- assign s  = shop.metafields["easy-pointly-loyalty"]["settings"].value -%}
{%- assign lp = customer.metafields["easy-pointly-loyalty"] -%}
{%- assign pts = lp.lifetime_points.value | plus: 0 -%}

{%- if s.t2Active and pts < s.t2Min -%}
  {%- assign next_name = s.t2Name -%}
  {%- assign next_min  = s.t2Min  -%}
{%- elsif s.t3Active and pts < s.t3Min -%}
  {%- assign next_name = s.t3Name -%}
  {%- assign next_min  = s.t3Min  -%}
{%- else -%}
  {%- assign next_name = "Max tier reached" -%}
{%- endif -%}

{%- if next_name != "Max tier reached" -%}
  <p>{{ next_min | minus: pts }} pts until {{ next_name }}</p>
{%- else -%}
  <p>You've reached the highest tier!</p>
{%- endif -%}

Note: The shop metafield is updated whenever a merchant saves their settings in the Easy Pointly admin. If you change tier thresholds, re-save once to push the update to this metafield.

Common calculations

Points → dollar value

There is no separate "value" metafield — compute it from points and pointsPerDollar at render time.

LIQUID EXAMPLE — display value in dollarsLiquid

{%- assign s     = shop.metafields["easy-pointly-loyalty"]["settings"].value -%}
{%- assign pts   = customer.metafields["easy-pointly-loyalty"]["points"].value | plus: 0 -%}
{%- assign value = pts | divided_by: s.pointsPerDollar -%}

<p>{{ pts }} pts = ${{ value | money_without_currency }}</p>