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

# Shop Object

> Reference for the shop.metafields.mage.loyalty JSON object.

The shop metafield contains your full loyalty program configuration. Access it in Liquid at:

```liquid theme={null}
{{ shop.metafields.mage.loyalty.value }}
```

<Note>
  Since the metafield type is `json`, you access nested properties through `.value` in Liquid.
</Note>

## Full object shape

```json theme={null}
{
  "points_program": {
    "enabled": true,
    "ways_to_earn": [
      {
        "name": "Place an order",
        "description": "Earn points for every dollar you spend",
        "points": 5,
        "type": "purchase",
        "category": "orders",
        "is_active": true,
        "customer_facing_label": "5 points per $1 spent",
        "call_to_action_url": null
      }
    ],
    "points_rewards": [
      {
        "name": "$5 Off",
        "points_cost": 500,
        "discount_type": "fixed",
        "discount_amount": 5.0,
        "minimum_spend": null,
        "is_active": true
      }
    ],
    "points_expiry_enabled": false,
    "points_expiry_days": null
  },
  "vip_program": {
    "enabled": true,
    "multiplier_mode": "multiplier",
    "tiers": [
      {
        "name": "Silver",
        "points_required": 0,
        "multiplier": 1.0,
        "badge_color": "#C0C0C0",
        "badge_image_url": null,
        "description": "Welcome to the program"
      },
      {
        "name": "Gold",
        "points_required": 1000,
        "multiplier": 1.5,
        "badge_color": "#FFD700",
        "badge_image_url": null,
        "description": "Earn 1.5x points on every purchase"
      }
    ]
  },
  "referral_program": {
    "enabled": true,
    "referral_rewards": [
      {
        "name": "10% Off for your friend",
        "discount_type": "percentage",
        "reward_type": "referred_customer"
      },
      {
        "name": "200 bonus points",
        "discount_type": "points",
        "reward_type": "referring_customer"
      }
    ],
    "social_settings": {
      "twitter": true,
      "facebook": true,
      "email": true,
      "whatsapp": false
    },
    "customer_account_required": false
  }
}
```

## Field reference

### `points_program`

| Field                   | Type           | Description                                 |
| ----------------------- | -------------- | ------------------------------------------- |
| `enabled`               | boolean        | Whether the points program is active        |
| `ways_to_earn`          | array          | List of earning rules                       |
| `points_rewards`        | array          | List of rewards available for redemption    |
| `points_expiry_enabled` | boolean        | Whether points expire                       |
| `points_expiry_days`    | number \| null | Days until points expire (null if disabled) |

### `points_program.ways_to_earn[]`

| Field                   | Type           | Description                                                 |
| ----------------------- | -------------- | ----------------------------------------------------------- |
| `name`                  | string         | Earning rule name                                           |
| `description`           | string \| null | Optional description                                        |
| `points`                | number         | Points awarded                                              |
| `type`                  | string         | Rule type (e.g. `purchase`, `signup`, `birthday`, `review`) |
| `category`              | string \| null | Rule category                                               |
| `is_active`             | boolean        | Whether the rule is currently active                        |
| `customer_facing_label` | string \| null | Display label for customers                                 |
| `call_to_action_url`    | string \| null | Optional URL for social/action rules                        |

### `points_program.points_rewards[]`

| Field             | Type           | Description                                                            |
| ----------------- | -------------- | ---------------------------------------------------------------------- |
| `name`            | string         | Reward name                                                            |
| `points_cost`     | number         | Points required to redeem                                              |
| `discount_type`   | string         | Discount type (`fixed`, `percentage`, `free_shipping`, `free_product`) |
| `discount_amount` | number \| null | Discount value (null for free shipping/product)                        |
| `minimum_spend`   | number \| null | Minimum order amount required                                          |
| `is_active`       | boolean        | Whether the reward is currently active                                 |

### `vip_program`

| Field             | Type           | Description                                              |
| ----------------- | -------------- | -------------------------------------------------------- |
| `enabled`         | boolean        | Whether the VIP program is active                        |
| `multiplier_mode` | string \| null | How multipliers are applied                              |
| `tiers`           | array          | List of VIP tiers (sorted by points required, ascending) |

### `vip_program.tiers[]`

| Field             | Type           | Description                                          |
| ----------------- | -------------- | ---------------------------------------------------- |
| `name`            | string         | Tier name                                            |
| `points_required` | number         | Lifetime points needed to reach this tier            |
| `multiplier`      | number         | Points earning multiplier (e.g. `1.5` = 1.5x points) |
| `badge_color`     | string \| null | Hex color for the tier badge                         |
| `badge_image_url` | string \| null | Custom badge image URL                               |
| `description`     | string \| null | Tier description                                     |

### `referral_program`

| Field                       | Type    | Description                                     |
| --------------------------- | ------- | ----------------------------------------------- |
| `enabled`                   | boolean | Whether the referral program is active          |
| `referral_rewards`          | array   | Rewards offered for referrals                   |
| `social_settings`           | object  | Which sharing channels are enabled              |
| `customer_account_required` | boolean | Whether referred friends must create an account |

### `referral_program.referral_rewards[]`

| Field           | Type   | Description                                                                         |
| --------------- | ------ | ----------------------------------------------------------------------------------- |
| `name`          | string | Reward name                                                                         |
| `discount_type` | string | Type of discount (`percentage`, `fixed`, `points`, `free_shipping`, `free_product`) |
| `reward_type`   | string | Who receives it (`referring_customer` or `referred_customer`)                       |

### `referral_program.social_settings`

| Field      | Type    | Description               |
| ---------- | ------- | ------------------------- |
| `twitter`  | boolean | Twitter/X sharing enabled |
| `facebook` | boolean | Facebook sharing enabled  |
| `email`    | boolean | Email sharing enabled     |
| `whatsapp` | boolean | WhatsApp sharing enabled  |