Skip to main content
Every shop runs its loyalty program in one of two modes, set by the merchant:
  • points The loyalty balance is plain points.
  • store_credit The loyalty balance is Mage store credit, denominated in money.
The API surface is identical in both modes. Every endpoint returns the same fields either way. What changes is how you interpret the numbers, and, for reward redemption, which flow is available.
This is Mage’s internal store credit, not Shopify native store credit. The loyalty engine treats both modes the same way, so points and store-credit shops share one API.

​
How values are denominated

In points mode, every points field is a whole number of points. In store_credit mode, the same fields hold the balance in the currency’s minor units. For most currencies that means cents, so 450 means 4.50 in the shop currency. For zero-decimal currencies such as JPY and KRW the factor is 1, so 450 means 450 yen. This applies to every points-named field the API returns or accepts, including current_points, lifetime_points, redeemed_points, a reward’s points_cost, an earning rule’s points, the adjustment on a points adjustment, and a tier’s threshold.
Inputs are always minor units in store-credit mode. To grant a customer 5.00 of credit on a GBP shop, send adjustment: 500, not adjustment: 5.

​
Detecting the mode

Responses that carry a loyalty value tell you the mode and currency so you can format correctly. Single-resource and list responses include loyalty_mode and currency in their meta, and the customer object carries loyalty_mode in its attributes.
loyalty_mode is always one of points or store_credit. currency is the shop’s ISO 4217 code (for example GBP), and defaults to USD when the shop has not set one.

​
The store_credit object

On store-credit shops, the customer object includes a store_credit object with pre-converted representations of the balance, so you do not have to do the minor-unit math yourself. In points mode it is null.

​
Credit companions on write responses

Endpoints that report a change to a customer’s balance (adjusting points, awarding an earning rule, recording a custom action, purchasing a reward) return credit_* companion fields alongside the raw minor-unit numbers. Each companion is the major-unit value as a decimal string. Companions appear only in store-credit mode; in points mode these fields are absent. For example, a points adjustment of 500 on a GBP store-credit shop returns:
The specific companion names for each endpoint are listed on that endpoint’s page. Webhook events use the same pattern (see Webhooks).

​
Redeeming rewards

In points mode a reward is redeemed with Purchase a reward, whether it is a standard fixed-cost reward or a flexible one. In store_credit mode, only flexible rewards can be redeemed. A standard fixed-cost reward returns 403 Forbidden with the detail This reward cannot be redeemed in store credit mode. A flexible reward lets the customer choose how much credit to spend, and the server pins the conversion at 1 minor unit of credit to 1 minor unit of discount. Read a reward’s redemption_mode and flexible_config from List rewards to know which flow applies and what range is valid.

​
Endpoints that carry mode context

These responses include loyalty_mode and currency: