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

# VIP tier object

> The VIP tier object represents a loyalty tier level.

VIP tiers define the levels of your loyalty program. Customers are automatically assigned to tiers based on their lifetime points.

## Attributes

| Field               | Type            | Description                                                                                                                                                        |
| ------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`              | string          | Tier display name                                                                                                                                                  |
| `description`       | string \| null  | Optional description                                                                                                                                               |
| `threshold`         | integer         | Entry value for the shop's primary entry method (see `entry_method` on the [list endpoint](/api-reference/vip-tiers/list)). For most shops this is lifetime points |
| `threshold_points`  | integer \| null | Points required when points is an additional entry method, otherwise `null`                                                                                        |
| `threshold_spend`   | integer \| null | Spend required when spend is an additional entry method, otherwise `null`                                                                                          |
| `threshold_orders`  | integer \| null | Orders required when orders is an additional entry method, otherwise `null`                                                                                        |
| `points_multiplier` | number          | Points earning multiplier for members of this tier                                                                                                                 |
| `position`          | integer         | The tier's rank, 1-indexed by `threshold` ascending (the lowest tier is `1`)                                                                                       |
| `badge_image_url`   | string \| null  | URL to the tier badge image                                                                                                                                        |
| `badge_color`       | string \| null  | Hex color code for the tier badge                                                                                                                                  |
| `rewards`           | array           | Tier-exclusive rewards automatically granted to members                                                                                                            |
| `created_at`        | string          | ISO 8601 timestamp                                                                                                                                                 |
| `updated_at`        | string          | ISO 8601 timestamp                                                                                                                                                 |

### Embedded rewards

Each item in the `rewards` array contains:

| Field             | Type            | Description                                                   |
| ----------------- | --------------- | ------------------------------------------------------------- |
| `id`              | string          | Reward ID                                                     |
| `name`            | string          | Reward name                                                   |
| `description`     | string \| null  | Optional description                                          |
| `discount_type`   | string          | Discount type                                                 |
| `reward_type`     | string          | The reward's type, typically `vip` for tier-exclusive rewards |
| `points_cost`     | integer         | Points cost                                                   |
| `discount_amount` | number          | Discount value                                                |
| `minimum_spend`   | number \| null  | Minimum order value                                           |
| `is_active`       | boolean         | Whether the reward is active                                  |
| `max_redemptions` | integer \| null | Maximum redemptions                                           |
| `expiry_days`     | integer \| null | Days until discount code expires                              |
| `created_at`      | string          | ISO 8601 timestamp                                            |
| `updated_at`      | string          | ISO 8601 timestamp                                            |

## Example

```json theme={null}
{
  "type": "vip_tier",
  "id": "tier_gold",
  "attributes": {
    "name": "Gold",
    "description": "Premium tier",
    "threshold": 500,
    "threshold_points": null,
    "threshold_spend": null,
    "threshold_orders": null,
    "points_multiplier": 1.5,
    "position": 2,
    "badge_image_url": null,
    "badge_color": "#FFD700",
    "rewards": [
      {
        "id": "reward_abc",
        "name": "£5 off your next order",
        "description": null,
        "discount_type": "fixed",
        "reward_type": "vip",
        "points_cost": 500,
        "discount_amount": 5.00,
        "minimum_spend": 20.00,
        "is_active": true,
        "max_redemptions": null,
        "expiry_days": 30,
        "created_at": "2024-01-01T00:00:00.000Z",
        "updated_at": "2024-01-01T00:00:00.000Z"
      }
    ],
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-01T00:00:00.000Z"
  }
}
```