# Prices

> Create, retrieve, update, and list prices for products.

A price defines the billing amount and interval for a [product](/docs/api-reference/products). One
product can have many prices — for example, a monthly and an annual option for the same plan.

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

- **id** `string` — Unique identifier for the price, e.g. `price_9Rz1wBqT`.
- **product** `string` (expandable) — The ID of the product this price belongs to, e.g. `prod_7Kc4mNpQ`. Expand to retrieve the full
  product object.
- **unit\_amount** `integer` — The unit amount in the smallest currency unit (e.g. cents), e.g. `2900` for €29.00.
- **currency** `string` — Three-letter ISO currency code, e.g. `EUR`.
- **recurring** `object` — Billing frequency for subscription prices.
  - **interval** `enum` — Billing interval: `month` or `year`.
  - **interval\_count** `integer` — Number of intervals between billings. `1` means every interval, `3` means every 3 months, etc.
- **active** `boolean` — Whether the price can be used for new purchases. Defaults to `true`.
- **nickname** `string` — An optional internal label for the price, e.g. `"Monthly (legacy)"`.
- **created** `integer` — Unix timestamp of when the price was created, e.g. `1716300000`.

## Create a price

Pass a `product`, `unit_amount`, `currency`, and optional `recurring` object to create a price.
Omit `recurring` for one-time prices.

`POST /v1/prices`

```bash
curl -X POST https://api.vinr.com/v1/prices \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d product=prod_7Kc4mNpQ \
-d unit_amount=2900 \
-d currency=EUR \
-d "recurring[interval]=month"
```

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

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

const price = await vinr.prices.create({
product: 'prod_7Kc4mNpQ',
unit_amount: 2900,
currency: 'EUR',
recurring: { interval: 'month' },
});
```

```python
import vinr

price = vinr.Price.create(
  product="prod_7Kc4mNpQ",
  unit_amount=2900,
  currency="EUR",
  recurring={"interval": "month"},
)
```

```ruby
price = Vinr::Price.create(
product: 'prod_7Kc4mNpQ',
unit_amount: 2900,
currency: 'EUR',
recurring: { interval: 'month' },
)
```

```json
{
"id": "price_9Rz1wBqT",
"product": "prod_7Kc4mNpQ",
"unit_amount": 2900,
"currency": "EUR",
"recurring": {
  "interval": "month",
  "interval_count": 1
},
"active": true,
"nickname": null,
"created": 1716300000
}
```

## Retrieve a price

`GET /v1/prices/{id}`

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

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

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

const price = await vinr.prices.retrieve('price_9Rz1wBqT');
```

```python
import vinr

price = vinr.Price.retrieve("price_9Rz1wBqT")
```

```ruby
price = Vinr::Price.retrieve('price_9Rz1wBqT')
```

```json
{
"id": "price_9Rz1wBqT",
"product": "prod_7Kc4mNpQ",
"unit_amount": 2900,
"currency": "EUR",
"recurring": {
  "interval": "month",
  "interval_count": 1
},
"active": true,
"nickname": null,
"created": 1716300000
}
```

## Update a price

Only `active` and `nickname` can be updated after creation. To change the amount, create a new
price and archive the old one by setting `active: false`.

`POST /v1/prices/{id}`

```bash
curl -X POST https://api.vinr.com/v1/prices/price_9Rz1wBqT \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d nickname="Monthly standard" \
-d active=true
```

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

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

const price = await vinr.prices.update('price_9Rz1wBqT', {
nickname: 'Monthly standard',
active: true,
});
```

```python
import vinr

price = vinr.Price.modify(
  "price_9Rz1wBqT",
  nickname="Monthly standard",
  active=True,
)
```

```ruby
price = Vinr::Price.update(
'price_9Rz1wBqT',
nickname: 'Monthly standard',
active: true,
)
```

```json
{
"id": "price_9Rz1wBqT",
"product": "prod_7Kc4mNpQ",
"unit_amount": 2900,
"currency": "EUR",
"recurring": {
  "interval": "month",
  "interval_count": 1
},
"active": true,
"nickname": "Monthly standard",
"created": 1716300000
}
```

## List prices

Returns a paginated list of prices. Filter by `product` to list all prices for a given product.

`GET /v1/prices`

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

```python
import vinr

prices = vinr.Price.list(
  product="prod_7Kc4mNpQ",
  active=True,
  limit=10,
)
```

```ruby
prices = Vinr::Price.list(
product: 'prod_7Kc4mNpQ',
active: true,
limit: 10,
)
```

```json
{
"object": "list",
"data": [
  {
    "id": "price_9Rz1wBqT",
    "product": "prod_7Kc4mNpQ",
    "unit_amount": 2900,
    "currency": "EUR",
    "recurring": {
      "interval": "month",
      "interval_count": 1
    },
    "active": true,
    "nickname": "Monthly standard",
    "created": 1716300000
  }
],
"has_more": false
}
```

## Related events

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