# Redemptions

> Create, retrieve, and list redemption records for coupons, rewards, and offers.

A redemption records the moment a customer redeems a coupon, reward, or offer. Each redemption is
immutable once created and serves as an audit trail for discount and loyalty activity.

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

- **id** `string` — Unique identifier for the redemption, e.g. `rdm_7Cw3nP`.
- **customer** `object` (expandable) — The customer who performed the redemption. Expand to retrieve the full customer object.
  - **id** `string` — Customer identifier, e.g. `cust_8aZ2`.
  - **email** `string` — Email address on the customer record.
- **redeemable\_id** `string` — The ID of the redeemed object — a coupon (`cpn_`), reward (`rwd_`), or offer (`ofr_`).
- **redeemable\_type** `enum` — One of `coupon`, `reward`, or `offer`.
- **amount\_off** `integer` — The discount value applied to the order in the smallest currency unit, if the redeemable was a
  discount coupon or offer. `null` for non-discount redeemables such as loyalty rewards.
- **redeemed\_at** `integer` — Unix timestamp when the customer completed the redemption.
- **created** `integer` — Unix timestamp when this redemption record was created.

## Create a redemption

Record a customer redeeming a coupon, reward, or offer. Set `redeemable_type` to indicate which kind
of redeemable is being applied.

`POST /v1/redemptions`

```bash
curl -X POST https://api.vinr.com/v1/redemptions \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d customer=cust_8aZ2 \
-d redeemable_id=cpn_5Hx1pR \
-d redeemable_type=coupon
```

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

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

const redemption = await vinr.redemptions.create({
customer: 'cust_8aZ2',
redeemable_id: 'cpn_5Hx1pR',
redeemable_type: 'coupon',
});
```

```python
import vinr

redemption = vinr.Redemption.create(
  customer="cust_8aZ2",
  redeemable_id="cpn_5Hx1pR",
  redeemable_type="coupon",
)
```

```ruby
redemption = Vinr::Redemption.create(
customer: 'cust_8aZ2',
redeemable_id: 'cpn_5Hx1pR',
redeemable_type: 'coupon',
)
```

```json
{
"id": "rdm_7Cw3nP",
"customer": "cust_8aZ2",
"redeemable_id": "cpn_5Hx1pR",
"redeemable_type": "coupon",
"amount_off": 500,
"redeemed_at": 1716300000,
"created": 1716300000
}
```

## Retrieve a redemption

Fetch a redemption record by its ID.

`GET /v1/redemptions/{id}`

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

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

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

const redemption = await vinr.redemptions.retrieve('rdm_7Cw3nP');
```

```python
import vinr

redemption = vinr.Redemption.retrieve("rdm_7Cw3nP")
```

```ruby
redemption = Vinr::Redemption.retrieve('rdm_7Cw3nP')
```

```json
{
"id": "rdm_7Cw3nP",
"customer": "cust_8aZ2",
"redeemable_id": "cpn_5Hx1pR",
"redeemable_type": "coupon",
"amount_off": 500,
"redeemed_at": 1716300000,
"created": 1716300000
}
```

## List redemptions

Returns a paginated list of redemptions. Filter by customer or redeemable type to narrow results.

| Parameter         | Type    | Description                                           |
| ----------------- | ------- | ----------------------------------------------------- |
| `customer`        | string  | Filter by customer ID.                                |
| `redeemable_type` | enum    | Filter by type: `coupon`, `reward`, or `offer`.       |
| `limit`           | integer | Number of results to return. Default `10`, max `100`. |

`GET /v1/redemptions`

```bash
curl "https://api.vinr.com/v1/redemptions?customer=cust_8aZ2&redeemable_type=coupon&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 redemptions = await vinr.redemptions.list({
customer: 'cust_8aZ2',
redeemable_type: 'coupon',
limit: 10,
});
```

```python
import vinr

redemptions = vinr.Redemption.list(
  customer="cust_8aZ2",
  redeemable_type="coupon",
  limit=10,
)
```

```ruby
redemptions = Vinr::Redemption.list(
customer: 'cust_8aZ2',
redeemable_type: 'coupon',
limit: 10,
)
```

```json
{
"object": "list",
"data": [
  {
    "id": "rdm_7Cw3nP",
    "customer": "cust_8aZ2",
    "redeemable_id": "cpn_5Hx1pR",
    "redeemable_type": "coupon",
    "amount_off": 500,
    "redeemed_at": 1716300000,
    "created": 1716300000
  }
],
"has_more": false
}
```

## Related events

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