# Tiers

> Create, retrieve, update, delete, and list membership tiers in the VINR loyalty programme.

A tier represents a membership level in the loyalty programme (e.g. Bronze, Silver, Gold). Customers
are automatically promoted or demoted based on their points balance relative to each tier's
`min_points` threshold.

> **Illustrative content.** Hand-authored to demonstrate the Standard/Advanced pattern; the production
> page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.

## The tier object

- **id** `string` — Unique identifier for the tier, e.g. `tier_gold`.
- **name** `string` — Human-readable tier name displayed to customers, e.g. `Gold`.
- **min\_points** `integer` — Minimum points balance required to qualify for this tier.
- **benefits** `array` — List of benefit descriptions shown to customers, e.g. `["Free shipping", "Early access"]`.
- **created** `integer` — Unix timestamp of when the tier was created.

## Create a tier

Define a new membership tier. Tiers are evaluated in ascending `min_points` order; a customer
qualifies for the highest tier whose `min_points` does not exceed their current balance.

`POST /v1/tiers`

```bash
curl -X POST https://api.vinr.com/v1/tiers \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d name=Gold \
-d min_points=5000 \
-d "benefits[]=Free shipping" \
-d "benefits[]=Early access to sales"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const tier = await vinr.tiers.create({
name: 'Gold',
min_points: 5000,
benefits: ['Free shipping', 'Early access to sales'],
});
```

```python
import vinr

tier = vinr.Tier.create(
  name="Gold",
  min_points=5000,
  benefits=["Free shipping", "Early access to sales"],
)
```

```ruby
tier = Vinr::Tier.create(
name: 'Gold',
min_points: 5000,
benefits: ['Free shipping', 'Early access to sales'],
)
```

```json
{
"id": "tier_gold",
"name": "Gold",
"min_points": 5000,
"benefits": [
  "Free shipping",
  "Early access to sales"
],
"created": 1716300000
}
```

## Retrieve a tier

Fetch a tier by its ID.

`GET /v1/tiers/{id}`

```bash
curl https://api.vinr.com/v1/tiers/tier_gold \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const tier = await vinr.tiers.retrieve('tier_gold');
```

```python
import vinr

tier = vinr.Tier.retrieve("tier_gold")
```

```ruby
tier = Vinr::Tier.retrieve('tier_gold')
```

```json
{
"id": "tier_gold",
"name": "Gold",
"min_points": 5000,
"benefits": [
  "Free shipping",
  "Early access to sales"
],
"created": 1716300000
}
```

## Update a tier

Update the tier's name or points threshold. Changes take effect immediately; affected customers'
tier assignments are re-evaluated on the next balance change.

`POST /v1/tiers/{id}`

```bash
curl -X POST https://api.vinr.com/v1/tiers/tier_gold \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d name=Platinum \
-d min_points=7500
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const tier = await vinr.tiers.update('tier_gold', {
name: 'Platinum',
min_points: 7500,
});
```

```python
import vinr

tier = vinr.Tier.modify(
  "tier_gold",
  name="Platinum",
  min_points=7500,
)
```

```ruby
tier = Vinr::Tier.update(
'tier_gold',
name: 'Platinum',
min_points: 7500,
)
```

```json
{
"id": "tier_gold",
"name": "Platinum",
"min_points": 7500,
"benefits": [
  "Free shipping",
  "Early access to sales"
],
"created": 1716300000
}
```

## Delete a tier

Permanently deletes a tier. Loyalty accounts currently assigned to this tier fall back to the next
qualifying tier automatically.

`DELETE /v1/tiers/{id}`

```bash
curl -X DELETE https://api.vinr.com/v1/tiers/tier_gold \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const deleted = await vinr.tiers.delete('tier_gold');
```

```python
import vinr

deleted = vinr.Tier.delete("tier_gold")
```

```ruby
deleted = Vinr::Tier.delete('tier_gold')
```

```json
{
"id": "tier_gold",
"deleted": true
}
```

## List tiers

Returns a paginated list of all tiers, ordered by `min_points` ascending.

| Parameter | Type    | Description                                           |
| --------- | ------- | ----------------------------------------------------- |
| `limit`   | integer | Number of results to return. Default `10`, max `100`. |

`GET /v1/tiers`

```bash
curl "https://api.vinr.com/v1/tiers?limit=10" \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const tiers = await vinr.tiers.list({ limit: 10 });
```

```python
import vinr

tiers = vinr.Tier.list(limit=10)
```

```ruby
tiers = Vinr::Tier.list(limit: 10)
```

```json
{
"object": "list",
"data": [
  {
    "id": "tier_bronze",
    "name": "Bronze",
    "min_points": 0,
    "benefits": ["Member discounts"],
    "created": 1716200000
  },
  {
    "id": "tier_silver",
    "name": "Silver",
    "min_points": 1000,
    "benefits": ["Member discounts", "Priority support"],
    "created": 1716200100
  },
  {
    "id": "tier_gold",
    "name": "Gold",
    "min_points": 5000,
    "benefits": ["Free shipping", "Early access to sales"],
    "created": 1716300000
  }
],
"has_more": false
}
```

## Related events

`tier.created` and `tier.updated`. See [Events](/docs/api-reference/events).