# Subscription Items

> Create, retrieve, update, delete, and list the price/quantity pairs within a subscription.

A subscription item represents a single price and quantity pair within a subscription. Multi-item
subscriptions use one item per price, letting you mix flat fees, per-seat charges, and metered usage
on a single billing cycle.

> **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 subscription item object

| Field          | Type      | Description                                     |
| -------------- | --------- | ----------------------------------------------- |
| `id`           | string    | Unique identifier, e.g. `si_7Bm3qR`.            |
| `subscription` | string    | The `sub_` this item belongs to. Expandable.    |
| `price`        | string    | The `price_` charged for this line. Expandable. |
| `quantity`     | integer   | Number of units (omitted for metered prices).   |
| `created`      | timestamp | Unix timestamp when the item was created.       |

## Create a subscription item

Add a new price to an existing subscription. VINR prorates the charge for the remainder of the
current period by default.

`POST /v1/subscription-items`

```bash
curl -X POST https://api.vinr.com/v1/subscription-items \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d subscription=sub_9Kpw1Vd \
-d price=price_per_seat \
-d quantity=5
```

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

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

const item = await vinr.subscriptionItems.create({
subscription: 'sub_9Kpw1Vd',
price: 'price_per_seat',
quantity: 5,
});
```

```python
import vinr

item = vinr.SubscriptionItem.create(
  subscription="sub_9Kpw1Vd",
  price="price_per_seat",
  quantity=5,
)
```

```ruby
item = Vinr::SubscriptionItem.create(
subscription: 'sub_9Kpw1Vd',
price: 'price_per_seat',
quantity: 5,
)
```

```json
{
"id": "si_7Bm3qR",
"subscription": "sub_9Kpw1Vd",
"price": "price_per_seat",
"quantity": 5,
"created": 1716300000
}
```

## Retrieve a subscription item

`GET /v1/subscription-items/{id}`

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

```js
const item = await vinr.subscriptionItems.retrieve('si_7Bm3qR');
```

```python
item = vinr.SubscriptionItem.retrieve("si_7Bm3qR")
```

```ruby
item = Vinr::SubscriptionItem.retrieve('si_7Bm3qR')
```

```json
{
"id": "si_7Bm3qR",
"subscription": "sub_9Kpw1Vd",
"price": "price_per_seat",
"quantity": 5,
"created": 1716300000
}
```

## Update a subscription item

Change the quantity or swap the price. VINR prorates the difference for the current period unless
you pass `proration_behavior: 'none'`.

`POST /v1/subscription-items/{id}`

```bash
curl -X POST https://api.vinr.com/v1/subscription-items/si_7Bm3qR \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d quantity=10
```

```js
const item = await vinr.subscriptionItems.update('si_7Bm3qR', {
quantity: 10,
});
```

```python
item = vinr.SubscriptionItem.modify(
  "si_7Bm3qR",
  quantity=10,
)
```

```ruby
item = Vinr::SubscriptionItem.update(
'si_7Bm3qR',
{ quantity: 10 },
)
```

```json
{
"id": "si_7Bm3qR",
"subscription": "sub_9Kpw1Vd",
"price": "price_per_seat",
"quantity": 10,
"created": 1716300000
}
```

## Delete a subscription item

Removes the item from the subscription. VINR generates a prorated credit for any unused time by
default; pass `proration_behavior=none` to skip the credit.

`DELETE /v1/subscription-items/{id}`

```bash
curl -X DELETE "https://api.vinr.com/v1/subscription-items/si_7Bm3qR?proration_behavior=create_prorations" \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
await vinr.subscriptionItems.delete('si_7Bm3qR', {
proration_behavior: 'create_prorations',
});
```

```python
vinr.SubscriptionItem.delete(
  "si_7Bm3qR",
  proration_behavior="create_prorations",
)
```

```ruby
Vinr::SubscriptionItem.delete(
'si_7Bm3qR',
{ proration_behavior: 'create_prorations' },
)
```

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

## List subscription items

Returns all items for a given subscription.

`GET /v1/subscription-items`

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

```js
const items = await vinr.subscriptionItems.list({
subscription: 'sub_9Kpw1Vd',
limit: 10,
});
```

```python
items = vinr.SubscriptionItem.list(
  subscription="sub_9Kpw1Vd",
  limit=10,
)
```

```ruby
items = Vinr::SubscriptionItem.list(
subscription: 'sub_9Kpw1Vd',
limit: 10,
)
```

```json
{
"object": "list",
"data": [
  {
    "id": "si_7Bm3qR",
    "subscription": "sub_9Kpw1Vd",
    "price": "price_per_seat",
    "quantity": 10,
    "created": 1716300000
  }
],
"has_more": false
}
```

## Related events

`customer.subscription.updated` is fired whenever items are added, changed, or removed. See
[Events](/docs/api-reference/events).