# Update a subscription item (/api/subscriptions/update-subscription-item)

`POST https://api.comecero.com/api/v1/subscriptions/{subscription_id}/items/{item_id}`

Changes an item's quantity, price or discount, or its `meta`. A change to `meta` or `cancellation_reason` only is saved at once with no charge. A change to quantity, price or discount applies now or at the end of the current period; when scheduled it shows in the item's `change_at_current_period_end`. Money can move. When the change applies at once, the customer pays the prorated amount for the rest of the current period now (from their account balance first, then their saved payment method) and an invoice is made; a cheaper replacement or lower quantity is refunded prorated, to the original payment method where possible, otherwise to the account balance. Whether a change applies at once or at the period end depends on the immediate upgrade and downgrade product types in your subscription settings, or on `apply_immediately`. On a live subscription only one money-moving change is allowed every 10 minutes. Use the preview endpoint first to show the customer the amount. Always answers `200` with the item. Secret, trusted and limited tokens may call it. A limited token only for the customer it is signed in as; it may change the quantity only (when your subscription settings allow customer upgrades or downgrades).

## Parameters

- `expand` (query): Comma-separated child objects to return in full instead of as a URL, for example `customer,payments`. Use dot notation for nested objects (`items.product`), up to four levels deep. A single object takes up to 12 paths; a list takes up to 2, applied to every item. Extra paths are dropped without an error. See [Expanding objects](https://docs.comecero.com/docs/basic-concepts/expanding-objects).
- `show` (query): Comma-separated fields to return; all others are left out. Use dot notation for child fields (`customer.email`). You cannot send `show` and `hide` together (`400`). See [Customizing output](https://docs.comecero.com/docs/basic-concepts/customizing-output).
- `hide` (query): Comma-separated fields to leave out of the response. Use dot notation for child fields (`customer.email`). You cannot send `show` and `hide` together (`400`). See [Customizing output](https://docs.comecero.com/docs/basic-concepts/customizing-output).
- `formatted` (query): When `true`, the object also has a `formatted` child with amounts and dates as display text in the shopper's language and currency (for example `$19.99` or `November 7, 2026`). The default is `false`. See [Localized formatting](https://docs.comecero.com/docs/basic-concepts/localized-formatting).

Request body: the `subscription_item_update_request` schema.

Responses: 200, 400, 401, 403, 404, 422, 500.

Full schemas: operation `update_subscription_item` in /openapi.json.