# Managing subscriptions

> Add items, change quantities, and update metadata.

Update a running subscription — change quantities, add or remove items, swap prices, and edit metadata — with predictable proration. This page covers the `subscriptions.update` API and how each change lands on the next invoice.

## What you can change

A subscription is a container of **subscription items**, each pairing a `price` with a `quantity`. Most edits are a mutation of that item list plus subscription-level settings.

| Change                  | How                         | Billing impact  |
| ----------------------- | --------------------------- | --------------- |
| Quantity (seats, units) | Update an item's `quantity` | Prorated        |
| Swap plan (price)       | Update an item's `price`    | Prorated        |
| Add a line (add-on)     | Append a new item           | Prorated        |
| Remove a line           | Delete an item              | Prorated credit |
| Metadata, fields        | Update the subscription     | None            |

> Quantity, price, and item changes generate **proration** line items — a credit for unused time on the old rate and a charge for the new one. See [Trials & proration](/docs/billing/trials-and-proration) for the math.

## Identifying items

Every subscription item has its own `si_`-prefixed id. Fetch the subscription first so you know which item to mutate.

```typescript
import { Vinr } from '@vinr/sdk';
const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const sub = await vinr.subscriptions.retrieve('sub_8Q2k...');
sub.items.forEach((item) => {
  console.log(item.id, item.price, item.quantity); // "si_..." "price_..." 3
});
```

## Changing quantity

The most common edit: a customer adds seats. Update the item by id.

```typescript
const updated = await vinr.subscriptions.update('sub_8Q2k...', {
  items: [{ id: 'si_47xR...', quantity: 5 }],
  prorationBehavior: 'create_prorations', // default
});
```

`prorationBehavior` controls how mid-cycle changes are billed:

| Field               | Type     | Description                                                       | Default |
| ------------------- | -------- | ----------------------------------------------------------------- | ------- |
| `create_prorations` | `string` | Default. Add credit + charge proration items to the next invoice. | `true`  |
| `always_invoice`    | `string` | Create prorations and immediately invoice for them now.           | `false` |
| `none`              | `string` | Apply the change but skip proration entirely.                     | `false` |

## Swapping a price (upgrade or downgrade)

To move a customer between plans, replace the item's `price`. Keep the same item `id` so VINR treats it as a swap rather than an add + remove.

```typescript
await vinr.subscriptions.update('sub_8Q2k...', {
  items: [{ id: 'si_47xR...', price: 'price_proYearly' }],
});
```

> Changing `recurring.interval` (e.g. monthly to yearly) resets the **billing cycle anchor** to now and invoices the remaining balance immediately. To preserve the original anchor, set `billingCycleAnchor: 'unchanged'`.

## Adding and removing items

Append an add-on by passing an item with no `id`; remove one by passing `deleted: true`.

```typescript
await vinr.subscriptions.update('sub_8Q2k...', {
  items: [
    { price: 'price_supportAddon', quantity: 1 }, // add
    { id: 'si_oldAddon', deleted: true },         // remove
  ],
});
```

A subscription with no remaining active items is invalid — to end billing entirely, [cancel the subscription](/docs/billing/subscriptions/cancellations) instead of deleting its last item.

## Updating metadata

Metadata changes never affect billing and never prorate. Use them to track internal references.

```typescript
await vinr.subscriptions.update('sub_8Q2k...', {
  metadata: { account_owner: 'team-emea', crm_id: 'AC-4192' },
});
```

## Resulting events

Each update emits events you can react to from a [webhook endpoint](/docs/integration/webhooks):

| Event                  | When                                                            |
| ---------------------- | --------------------------------------------------------------- |
| `subscription.updated` | Any item, quantity, price, or metadata change.                  |
| `invoice.created`      | A proration draft invoice is generated (with `always_invoice`). |
| `invoice.paid`         | The proration invoice is collected.                             |

```typescript
const event = vinr.webhooks.verify(payload, signatureHeader); // x-vinr-signature
if (event.type === 'subscription.updated') {
  const sub = event.data.object;
  syncEntitlements(sub.customer, sub.items); // grant/revoke seats
}
```

> Always reconcile entitlements from `subscription.updated`, not from your API response — the webhook is the source of truth and fires even when changes originate from the dashboard or [dunning](/docs/billing/dunning-and-recovery).

## Edge cases

#### The subscription is in a trial

Updates during a trial do not prorate — there is nothing billed yet. The new configuration takes effect when the trial ends and the first real invoice is generated.

#### A downgrade produces a credit larger than the next invoice

The surplus becomes **customer credit balance** and is automatically applied to future invoices. VINR never issues a cash refund for a downgrade unless you explicitly create one.

#### An update lands while an invoice is past\_due

The change is accepted, but new proration items wait for the open invoice to settle. Resolve collection through dunning first; see [Troubleshooting failed payments](/docs/troubleshooting/declines-and-failures).

#### You need to preview the cost before committing

Call the invoice preview endpoint with the proposed `items` to see exact proration amounts without mutating the subscription. See [Invoice items](/docs/api-reference/invoice-items).

## Next steps

[Trials & proration](/docs/billing/trials-and-proration) — How mid-cycle changes are calculated.

[Canceling subscriptions](/docs/billing/subscriptions/cancellations) — End billing and handle final invoices.

[Subscriptions](/docs/billing/subscriptions) — The full subscription lifecycle.