# Rewards

> Create, retrieve, and list rewards that customers can redeem with their loyalty points.

A reward is a redemption option within the loyalty programme. Rewards have a points cost and can
represent a discount percentage, a free item, or any other benefit you define.

> **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 reward object

- **id** `string` — Unique identifier for the reward, e.g. `rwd_5Hx2nP`.
- **name** `string` — Human-readable name shown to customers, e.g. `10% Off Next Order`.
- **points\_cost** `integer` — Number of points a customer must spend to redeem this reward.
- **type** `enum` — Either `discount` (a percentage off) or `item` (a free product or service).
- **value** `string` — For `discount` rewards: the percentage as a string, e.g. `"10"`. For `item` rewards: a
  description of what is granted, e.g. `"Free coffee"`.
- **active** `boolean` — Whether the reward is currently available for redemption. Inactive rewards are hidden from
  customers but their historical redemptions are preserved.
- **created** `integer` — Unix timestamp of when the reward was created.

## Create a reward

Define a new redemption option. Set `active: true` (the default) to make it immediately available
to customers with sufficient points.

`POST /v1/rewards`

```bash
curl -X POST https://api.vinr.com/v1/rewards \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d name="10% Off Next Order" \
-d points_cost=500 \
-d type=discount \
-d value=10
```

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

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

const reward = await vinr.rewards.create({
name: '10% Off Next Order',
points_cost: 500,
type: 'discount',
value: '10',
});
```

```python
import vinr

reward = vinr.Reward.create(
  name="10% Off Next Order",
  points_cost=500,
  type="discount",
  value="10",
)
```

```ruby
reward = Vinr::Reward.create(
name: '10% Off Next Order',
points_cost: 500,
type: 'discount',
value: '10',
)
```

```json
{
"id": "rwd_5Hx2nP",
"name": "10% Off Next Order",
"points_cost": 500,
"type": "discount",
"value": "10",
"active": true,
"created": 1716300000
}
```

## Retrieve a reward

Fetch a reward by its ID.

`GET /v1/rewards/{id}`

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

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

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

const reward = await vinr.rewards.retrieve('rwd_5Hx2nP');
```

```python
import vinr

reward = vinr.Reward.retrieve("rwd_5Hx2nP")
```

```ruby
reward = Vinr::Reward.retrieve('rwd_5Hx2nP')
```

```json
{
"id": "rwd_5Hx2nP",
"name": "10% Off Next Order",
"points_cost": 500,
"type": "discount",
"value": "10",
"active": true,
"created": 1716300000
}
```

## List rewards

Returns a paginated list of rewards. Pass `active=true` to show only currently redeemable rewards.

| Parameter | Type    | Description                                           |
| --------- | ------- | ----------------------------------------------------- |
| `active`  | boolean | Filter by active status. Omit to return all rewards.  |
| `limit`   | integer | Number of results to return. Default `10`, max `100`. |

`GET /v1/rewards`

```bash
curl "https://api.vinr.com/v1/rewards?active=true&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 rewards = await vinr.rewards.list({
active: true,
limit: 10,
});
```

```python
import vinr

rewards = vinr.Reward.list(
  active=True,
  limit=10,
)
```

```ruby
rewards = Vinr::Reward.list(
active: true,
limit: 10,
)
```

```json
{
"object": "list",
"data": [
  {
    "id": "rwd_5Hx2nP",
    "name": "10% Off Next Order",
    "points_cost": 500,
    "type": "discount",
    "value": "10",
    "active": true,
    "created": 1716300000
  }
],
"has_more": false
}
```

## Related events

`reward.created`. See [Events](/docs/api-reference/events).