---
title: "Update a subscription item"
method: PATCH
path: "/subscriptions/{subscription_id}/items/{id}"
tags: ["Subscription items"]
---

# Update a subscription item

`PATCH /subscriptions/{subscription_id}/items/{id}`

Updates an item of a subscription. Pass `quantity` to change the number of units, and `price_data` to replace the item's price with a newly created one. When the subscription has other items, the new price must use a currency compatible with theirs (a `CLF` price bills within a `CLP` subscription) and the same recurring `interval`. You can replace the price of a subscription's only item with any currency. Changes take effect on the subscription's next invoice, with no proration for the current billing period.

## Path parameters

- `subscription_id` string, required
- `id` string, required

## Request body

- object
  - `price_data` object — Definition of a new price for the item. Fintoc replaces the current price with a newly created one.
    - `currency` 'CLF' | 'CLP' | 'MXN', required — Three-letter ISO 4217 currency code, in uppercase. One of `CLP`, `MXN`, or `CLF`. A `CLF` (UF) price is billable within a `CLP` subscription.
    - `recurring` object, required — Billing cadence of the price. Must match the cadence of the subscription's other items.
      - `interval` 'month' | 'year', required — Frequency at which the price bills. One of `month` or `year`.
      - `interval_count` integer, required — Number of intervals between each billing cycle. For example, `interval: "month"` with `interval_count: 3` bills every 3 months.
    - `unit_amount` integer, required — Amount the price bills per unit, in the smallest unit of the currency. CLP has no decimals, so `10000` is $10,000 CLP; MXN uses centavos, so `10000` is $100.00 MXN.
    - `product` string — ID of an existing product the price belongs to. Mutually exclusive with `product_data`; exactly one of the two is required.
    - `product_data` object — Inline definition of a new product for the price. Mutually exclusive with `product`; exactly one of the two is required.
      - `name` string, required — Name of the product.
      - `description` string — Free-text description of the product.
      - `image_url` string — HTTPS URL of an image of the product.
      - `metadata` object — Set of key-value pairs to attach to the product. Nested objects and arrays are not allowed as values.
  - `quantity` integer — Number of units of the price the item bills for. Must be greater than zero.

## Response `200`

The updated subscription item.

- SubscriptionItem
  - `id` string, required — Unique identifier of the subscription item.
  - `object` 'subscription_item', required — Type of the object. Always `subscription_item`.
  - `price` object, required — Price the item bills for on every billing cycle.
    - `currency` 'CLF' | 'CLP' | 'MXN', required — Three-letter ISO 4217 currency code, returned in uppercase. One of `CLP`, `MXN` or `CLF`.
    - `product` object, required — Product the price belongs to.
      - `id` string, required — Unique identifier of the product.
      - `object` 'product', required — Type of the object. Always `product`.
      - `created_at` string, date-time, required — ISO 8601 timestamp of when the product was created.
      - `description` string, nullable, required — Free-text description of the product.
      - `image_url` string, nullable, required — HTTPS URL of an image of the product.
      - `metadata` object, required — Set of key-value pairs attached to the product.
      - `mode` 'live' | 'test', required — Mode of the object. One of `live` or `test`. `test` products use fake data for integration testing.
      - `name` string, required — Name of the product.
    - `recurring` object, required — Billing cadence of the price.
      - `interval` 'month' | 'year', required — Frequency at which the price bills. One of `month` or `year`.
      - `interval_count` integer, required — Number of intervals between each billing cycle. For example, `interval: "month"` with `interval_count: 3` bills every 3 months.
    - `unit_amount` integer, required — Amount the price bills per unit, in the smallest unit of the currency. CLP has no decimals, so `10000` is $10,000 CLP; MXN uses centavos, so `10000` is $100.00 MXN.
  - `quantity` integer, required — Number of units of the price the item bills for.

## Other responses

- `400` — Invalid request: a parameter is invalid.
- `401` — Invalid or missing API key.
- `404` — The subscription or the item does not exist, or belongs to another organization or mode.
- `409` — The new price uses a currency incompatible with, or a recurring interval different from, the subscription's other items.

---

[API](https://skmtc.net/fintoc/apis/fintoc-api.md) · [All operations](https://skmtc.net/fintoc/apis/fintoc-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fintoc/fintoc-api/versions/9dafa63688a3/schema)