---
title: "Update a subscription"
method: PATCH
path: "/subscriptions/{id}"
tags: ["Subscriptions"]
---

# Update a subscription

`PATCH /subscriptions/{id}`

Updates a subscription. Provide at least one of `trial_end` or `payment_method`.

Provide `trial_end` to set when the trial ends and the first paid billing period begins. `trial_end` must be at least one day in the future. Fintoc aligns the subscription's `billing_cycle_anchor` to `trial_end` and sets its `status` to `trialing` until then.

Provide `payment_method` to swap the payment method the subscription charges against. The payment method must be active, belong to the subscription's customer, and be a `pac` or `card`. After the swap, Fintoc charges every next payment against the new payment method, including any invoice that is already open. Swapping does not charge the subscription immediately.

Canceled subscriptions cannot be updated.

## Path parameters

- `id` string, required

## Request body

- union
  - object
    - `trial_end` string, date-time, required — ISO 8601 datetime, in UTC, when the trial ends and the first paid billing period begins. Must be at least one day in the future. Fintoc sets the subscription's `billing_cycle_anchor` to this time.
    - `payment_method` string — Payment method ID to charge every next payment against, including any invoice that is already open. Must be active, belong to the subscription's customer, and be one of `pac` or `card`.
  - object
    - `trial_end` string, date-time — ISO 8601 datetime, in UTC, when the trial ends and the first paid billing period begins. Must be at least one day in the future. Fintoc sets the subscription's `billing_cycle_anchor` to this time.
    - `payment_method` string, required — Payment method ID to charge every next payment against, including any invoice that is already open. Must be active, belong to the subscription's customer, and be one of `pac` or `card`.

## Response `200`

The updated subscription. When you set `trial_end`, `status` is `trialing` until the trial ends. When you set `payment_method`, the subscription points to the new payment method.

- Subscription
  - `id` string, required — Unique identifier of the subscription.
  - `object` 'subscription', required — Type of the object. Always `subscription`.
  - `billing_cycle_anchor` string, date-time, required — ISO 8601 timestamp that anchors the billing cycle. Fintoc sets this anchor to the subscription's creation time, or to `trial_end` when a trial applies. Fintoc measures every billing period from this anchor.
  - `collection_method` 'charge_automatically' | 'send_invoice', required — Method Fintoc uses to collect the invoices the subscription generates. One of `charge_automatically` (Fintoc charges the saved payment method) or `send_invoice` (Fintoc sends the invoice for the customer to pay). Subscriptions created through the API always use `send_invoice`.
  - `created_at` string, date-time, required — ISO 8601 timestamp of when the subscription was created.
  - `customer` string, required — ID of the customer the subscription bills.
  - `items` SubscriptionItem[], required — Items the subscription bills for on every billing cycle.
    - `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.
  - `metadata` object, required — Set of key-value pairs attached to the subscription.
  - `mode` 'live' | 'test', required — Mode of the object. One of `live` or `test`. `test` subscriptions use fake data for integration testing and do not collect real money.
  - `payment_method` string, nullable, required — ID of the payment method charged when `collection_method` is `charge_automatically`. Always `null` for subscriptions created through the API.
  - `status` 'active' | 'canceled' | 'incomplete' | 'trialing', required — Current status of the subscription. One of `active`, `incomplete` (the first invoice payment has not yet succeeded), `trialing` (the trial period has not ended), or `canceled` (the subscription stopped generating invoices).
  - `trial_end` string, date-time, nullable, required — ISO 8601 timestamp at which the trial period ends, or `null` if the subscription has no trial.

## Other responses

- `400` — Invalid request: provide `trial_end`, `payment_method`, or both. `trial_end` must be a valid ISO 8601 datetime and at least one day in the future.
- `401` — Invalid or missing API key.
- `404` — The subscription does not exist, belongs to another organization, or belongs to a different API key mode. The `payment_method` does not exist or belongs to a different customer.
- `409` — The subscription cannot be updated in its current state, for example because it is canceled.
- `422` — The `payment_method` cannot be used for this subscription. The payment method is inactive or has an unsupported type. Subscriptions accept `pac` or `card`, not `bank_transfer`.

---

[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)