> ## Documentation Index
> Fetch the complete documentation index at: https://developers.mageloyalty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Loyalty modes

> How the API represents points and store credit, and how to read loyalty values in each mode.

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.

<Note>
  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.
</Note>

## 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`.

|                                  | `points` mode        | `store_credit` mode                         |
| -------------------------------- | -------------------- | ------------------------------------------- |
| Unit                             | Whole points         | Currency minor units                        |
| `current_points: 450` means      | 450 points           | 4.50 in the shop currency (450 for JPY/KRW) |
| Input values (e.g. `adjustment`) | Whole points         | Minor units                                 |
| Reward redemption                | Standard or flexible | Flexible only                               |

<Warning>
  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`.
</Warning>

## 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.

```json theme={null}
{
  "data": { "type": "customer", "id": "6789012345", "attributes": { "...": "..." } },
  "meta": {
    "loyalty_mode": "store_credit",
    "currency": "GBP"
  }
}
```

`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`.

| Field               | Type    | Description                                                          |
| ------------------- | ------- | -------------------------------------------------------------------- |
| `balance_minor`     | integer | The balance in minor units (identical to `current_points`)           |
| `balance`           | string  | The balance in major units as a decimal string, for example `"4.50"` |
| `balance_formatted` | string  | A localized display string, for example `"£4.50"`                    |
| `currency`          | string  | The ISO 4217 currency code                                           |

```json theme={null}
"store_credit": {
  "balance_minor": 450,
  "balance": "4.50",
  "balance_formatted": "£4.50",
  "currency": "GBP"
}
```

## 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:

```json theme={null}
{
  "adjustment": 500,
  "points_before": 200,
  "points_after": 700,
  "current_points": 700,
  "loyalty_mode": "store_credit",
  "currency": "GBP",
  "credit_adjustment": "5.00",
  "credit_before": "2.00",
  "credit_after": "7.00",
  "credit_balance": "7.00"
}
```

The specific companion names for each endpoint are listed on that endpoint's page. Webhook events use the same pattern (see [Webhooks](/api-reference/webhooks/getting-started)).

## Redeeming rewards

In `points` mode a reward is redeemed with [Purchase a reward](/api-reference/rewards/purchase), 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](/api-reference/rewards/list) to know which flow applies and what range is valid.

## Endpoints that carry mode context

These responses include `loyalty_mode` and `currency`:

* [Get a customer](/api-reference/customers/get), [List customers](/api-reference/customers/list), [Enroll a customer](/api-reference/customers/enroll), [Update a customer](/api-reference/customers/update) (customer object plus list `meta`)
* [Adjust points](/api-reference/customers/adjust-points)
* [List](/api-reference/customers/list-earning-history) and [get earning history](/api-reference/customers/get-earning-history)
* [List](/api-reference/customers/list-reward-history) and [get reward history](/api-reference/customers/get-reward-history)
* [List earning rules](/api-reference/earning-rules/list), [Award an earning rule](/api-reference/earning-rules/award), [Record a custom action](/api-reference/earning-rules/award-custom-action)
* [List rewards](/api-reference/rewards/list), [Purchase a reward](/api-reference/rewards/purchase)
* [List VIP tiers](/api-reference/vip-tiers/list), [Get a VIP tier](/api-reference/vip-tiers/get)
* The `points.earned`, `points.redeemed`, `customer.tier_upgrade`, and `customer.tier_downgrade` webhook events