Loyalty modes - Mage Loyalty Documentation

Every Mage shop runs in one of two loyalty modes, chosen by the merchant:

points The loyalty balance is plain points.
store_credit The loyalty balance is Mage store credit, denominated in money.

The loyalty engine and every SDK method behave identically in both modes. The SDK returns the same fields either way. What changes is how you interpret and display the numbers, and, for redemption, which method a customer uses.

Store credit here means Mage’s internal store credit, not Shopify native store credit.

How each mode denominates values

Every loyalty number the SDK returns (points, lifetimePoints, redeemedPoints, a reward’s pointsCost, an earning rule’s award) is read in the shop’s loyalty unit:

	`points` mode	`store_credit` mode
Unit	Whole points	Currency minor units
`points: 450` means	450 points	4.50 in the shop currency (or 450 for zero-decimal currencies like JPY/KRW)
Displayed as	`"450"`	`"$4.50"`
Redemption	`redeemReward` or `redeemFlexible`	`redeemFlexible` only

Because the raw numbers look the same in both modes, never assume points. Read the mode and format through the helpers below.

Detecting the mode

Methods that carry loyalty amounts return loyaltyMode and currency alongside their data. These are getCustomerDetails, getCustomerActivity, getShopRewards, getEarningRules, and getShopVipTiers.

MageSDK.getCustomerDetails().then(function(resp) {
  if (!resp.success) return;

  var customer = resp.data.customer;
  var mode = resp.data.loyaltyMode;   // 'points' | 'store_credit'
  var currency = resp.data.currency;  // e.g. 'USD'

  var balance = MageSDK.formatLoyaltyValue(customer.points, mode, currency);
  document.getElementById('balance').textContent = balance;
  // points mode  -> "450"
  // credit mode  -> "$4.50"
});

The same formatLoyaltyValue call handles both modes, so your rendering code stays mode-agnostic. Pass the mode and currency straight through and let the helper decide.

Formatting helpers

The SDK exposes helpers on window.MageSDK so you never reimplement the unit math. Each one works in both modes.

formatLoyaltyValue(value, mode?, currency?)

string

Formats a loyalty value for display. Points mode returns the number with locale grouping ("1,250"). Store-credit mode returns a localized currency string ("$12.50").

formatSignedLoyaltyValue(value, mode?, currency?)

string

Same as formatLoyaltyValue but prefixes a + or - sign. Useful for activity rows ("+150", "+$3.00", "-300").

loyaltyUnitLabel(mode?, count?)

string

Returns "point" or "points" in points mode (based on count), and an empty string in store-credit mode, where the money value already describes itself.

resolveLoyaltyMode(mode?)

string

Normalizes any input to 'points' or 'store_credit'. Anything that isn’t exactly 'store_credit' resolves to 'points', so an older server or a missing value safely defaults to points.

isStoreCredit(mode?)

boolean

Convenience check. Returns true when the resolved mode is 'store_credit'.

minorToMajor(amountMinor, currency?)

number

Converts a minor-unit amount to major units (300 becomes 3 for USD, 500 stays 500 for JPY). Relevant in store-credit mode when you need the raw number. For display, prefer formatLoyaltyValue.

// Points mode
MageSDK.formatLoyaltyValue(1250, 'points', 'USD');            // "1,250"
MageSDK.formatSignedLoyaltyValue(150, 'points', 'USD');       // "+150"
MageSDK.loyaltyUnitLabel('points', 1);                        // "point"

// Store-credit mode
MageSDK.formatLoyaltyValue(1250, 'store_credit', 'USD');      // "$12.50"
MageSDK.formatLoyaltyValue(500, 'store_credit', 'JPY');       // "¥500"
MageSDK.formatSignedLoyaltyValue(-300, 'store_credit', 'USD'); // "-$3.00"
MageSDK.isStoreCredit('store_credit');                        // true

The storeCredit convenience object

In store-credit mode, getCustomerDetails attaches a ready-to-display storeCredit object to the customer. In points mode it is null, so you can branch on its presence.

{
  "storeCredit": {
    "balanceMinor": 450,
    "balance": "4.50",
    "balanceFormatted": "$4.50",
    "currency": "USD"
  }
}

balanceMinor

number

The raw balance in minor units. Identical to customer.points in store-credit mode.

balance

string

The balance in major units as a decimal string, e.g. "4.50".

balanceFormatted

string

A localized display string, e.g. "$4.50".

currency

string

The ISO currency code.

Redemption differs by mode

Redemption is the one behavior that is not identical across modes. Points mode supports both redemption methods:

redeemReward for fixed rewards (a set cost for a set discount).
redeemFlexible for flexible rewards (the customer chooses how much to spend).

Store-credit mode supports only flexible redemption. Calling redeemReward there returns:

{
  "success": false,
  "error": "This reward cannot be redeemed in store credit mode"
}

So in store-credit shops, redeem through redeemFlexible. A reward is redeemable this way when its redemptionMode is "flexible"; read the amount bounds from the reward’s flexibleConfig (minPoints / maxPoints).

MageSDK.getShopRewards().then(function(resp) {
  if (!resp.success) return;

  var flexible = resp.data.regularRewards.filter(function(r) {
    return r.redemptionMode === 'flexible';
  });

  var reward = flexible[0];
  if (!reward) return;

  // Spend the customer's chosen amount (here, the configured minimum)
  var amount = reward.flexibleConfig.minPoints;

  MageSDK.redeemFlexible(reward.id, amount).then(function(res) {
    if (res.success) {
      console.log('Discount code:', res.data.customerReward.discountCode);
      console.log('Value:', res.data.discountAmount);
    } else {
      console.log('Error:', res.error);
    }
  });
});

If you want redemption code that works regardless of mode, drive it off the reward’s redemptionMode: call redeemReward for "fixed" rewards and redeemFlexible for "flexible" rewards. Store-credit shops only surface flexible rewards, so this pattern naturally does the right thing in both modes.

​How each mode denominates values

​Detecting the mode

​Formatting helpers

​The storeCredit convenience object

​Redemption differs by mode

How each mode denominates values

Detecting the mode

Formatting helpers

The storeCredit convenience object

Redemption differs by mode