---
title: "Update Subscription"
method: PUT
path: "/subscriptions/{subscription_id}"
tags: ["Subscriptions"]
---

# Update Subscription

`PUT /subscriptions/{subscription_id}`

Update an existing `Subscription` resource, typically used for subscriptions created without a `Subscription Plan`. Note that you can only update specific resource fields.

Two common use cases for updating a `Subscription` are:

### Updating the payment amount

This operation allows for adjusting the payment amount, such as when a subscriber decides to donate more or less money to a charity or upgrade/downgrade a product or service.

### Updating billing details

If the subscriber wishes to change their payment details, you can update the [`buyer_details.instrument_id`] property with a new [`Payment Instrument`](#Payment-Instruments).

## Request body

- union
  - UpdateSubscription
    - `amount` integer — The total amount that will be debited in cents (e.g. 100 cents to debit $1.00). This field can be updated only for subscriptions *not* created from subscription plans.
    - `billing_cycle_day` integer, nullable — The day of the month on which the `Subscription` is billed. Only applies to subscriptions with a monthly billing cycle (e.g., `MONTHLY`, `BIMONTHLY`, `QUARTERLY`, `SEMIYEARLY`, `YEARLY`, `BIYEARLY`, `TRIYEARLY`). If the specified day doesn't exist in a given month (e.g., April 31), the subscription is billed on the last valid day of that month. Accepted values are 1 to 31.
    - `buyer_details` object — An object containing details about the buyer.
      - `identity_id` string — The [identity ID](/api/identities) of the buyer.
      - `instrument_id` unknown
      - `requested_delivery_methods` object[] — A list of requested delivery methods. Each method specifies the type of delivery and the destination(s) where the receipt should be sent.
        - `type` 'EMAIL' | 'SMS' | 'PRINT', required — The method of receipt delivery.
        - `destinations` string[], required — A list of destination addresses or identifiers where the receipt should be sent.
      - `shipping_address` Address
        - `line1` string, nullable, required — First line of the address (max 35 characters).
        - `line2` string, nullable — Second line of the address (max 35 characters).
        - `city` string, nullable, required — City (max 20 characters).
        - `region` string, nullable, required — 2-letter State code.
        - `postal_code` string, nullable, required — Zip or Postal code (max 7 characters).
        - `country` 'ABW' | 'AFG' | 'AGO' | 'AIA' | 'ALA' | 'ALB' | 'AND' | 'ARE' | 'ARG' | 'ARM' | 'ASM' | 'ATA' | 'ATF' | 'ATG' | 'AUS' | 'AUT' | 'AZE' | 'BDI' | 'BEL' | 'BEN' | 'BES' | 'BFA' | 'BGD' | 'BGR' | 'BHR' | 'BHS' | 'BIH' | 'BLM' | 'BLR' | 'BLZ' | 'BMU' | 'BOL' | 'BRA' | 'BRB' | 'BRN' | 'BTN' | 'BVT' | 'BWA' | 'CAF' | 'CAN' | 'CCK' | 'CHE' | 'CHL' | 'CHN' | 'CIV' | 'CMR' | 'COD' | 'COG' | 'COK' | 'COL' | 'COM' | 'CPV' | 'CRI' | 'CUB' | 'CUW' | 'CXR' | 'CYM' | 'CYP' | 'CZE' | 'DEU' | 'DJI' | 'DMA' | 'DNK' | 'DOM' | 'DZA' | 'ECU' | 'EGY' | 'ERI' | 'ESH' | 'ESP' | 'EST' | 'ETH' | 'FIN' | 'FJI' | 'FLK' | 'FRA' | 'FRO' | 'FSM' | 'GAB' | 'GBR' | 'GEO' | 'GGY' | 'GHA' | 'GIB' | 'GIN' | 'GLP' | 'GMB' | 'GNB' | 'GNQ' | 'GRC' | 'GRD' | 'GRL' | 'GTM' | 'GUF' | 'GUM' | 'GUY' | 'HKG' | 'HMD' | 'HND' | 'HRV' | 'HTI' | 'HUN' | 'IDN' | 'IMN' | 'IND' | 'IOT' | 'IRL' | 'IRN' | 'IRQ' | 'ISL' | 'ISR' | 'ITA' | 'JAM' | 'JEY' | 'JOR' | 'JPN' | 'KAZ' | 'KEN' | 'KGZ' | 'KHM' | 'KIR' | 'KNA' | 'KOR' | 'KWT' | 'LAO' | 'LBN' | 'LBR' | 'LBY' | 'LCA' | 'LIE' | 'LKA' | 'LSO' | 'LTU' | 'LUX' | 'LVA' | 'MAC' | 'MAF' | 'MAR' | 'MCO' | 'MDA' | 'MDG' | 'MDV' | 'MEX' | 'MHL' | 'MKD' | 'MLI' | 'MLT' | 'MMR' | 'MNE' | 'MNG' | 'MNP' | 'MRT' | 'MSR' | 'MTQ' | 'MUS' | 'MWI' | 'MYS' | 'MYT' | 'NAM' | 'NCL' | 'NER' | 'NFK' | 'NGA' | 'NIC' | 'NIU' | 'NLD' | 'NOR' | 'NPL' | 'NRU' | 'NZL' | 'OMN' | 'PAK' | 'PAN' | 'PCN' | 'PER' | 'PHL' | 'PLW' | 'PNG' | 'POL' | 'PRI' | 'PRK' | 'PRT' | 'PRY' | 'PSE' | 'PYF' | 'QAT' | 'REU' | 'ROU' | 'RUS' | 'RWA' | 'SAU' | 'SDN' | 'SEN' | 'SGP' | 'SGS' | 'SHN' | 'SJM' | 'SLB' | 'SLE' | 'SLV' | 'SMR' | 'SOM' | 'SPM' | 'SRB' | 'SSD' | 'STP' | 'SUR' | 'SVK' | 'SVN' | 'SWE' | 'SWZ' | 'SXM' | 'SYC' | 'SYR' | 'TCA' | 'TCD' | 'TGO' | 'THA' | 'TJK' | 'TKL' | 'TKM' | 'TLS' | 'TON' | 'TTO' | 'TUN' | 'TUR' | 'TUV' | 'TWN' | 'TZA' | 'UGA' | 'UKR' | 'UMI' | 'URY' | 'USA' | 'UZB' | 'VAT' | 'VCT' | 'VEN' | 'VGB' | 'VIR' | 'VNM' | 'VUT' | 'WLF' | 'WSM' | 'XKX' | 'YEM' | 'ZAF' | 'ZMB' | 'ZWE', nullable, required
    - `nickname` string — A human-readable name for the resource.
    - `subscription_details` object — An object containing subscription details.
      - `send_invoice` boolean — Whether to send the user an invoice.
      - `send_receipt` boolean — Whether to send the user a receipt.
    - `tags` Tags, nullable — Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`)
  - UpdateSubscriptionNewPlan
    - `subscription_plan_id` string — The ID of the new `Subscription Plan` on which the `Subscription` is based.

## Response `200`

A single `Subscription`

- Subscription
  - `id` string — The ID of the resource.
  - `created_at` string, date-time — Timestamp of when the object was created.
  - `updated_at` string, date-time — Timestamp of when the object was last updated.
  - `amount` integer — The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).
  - `application_id` string — The ID of the `Application` associated with the `Subscription`.
  - `billing_cycle_day` integer, nullable — The day of the month on which the `Subscription` is billed. Only applies to subscriptions with a monthly billing cycle (e.g., `MONTHLY`, `BIMONTHLY`, `QUARTERLY`, `SEMIYEARLY`, `YEARLY`, `BIYEARLY`, `TRIYEARLY`). If the specified day doesn't exist in a given month (e.g., April 31), the subscription is billed on the last valid day of that month. Accepted values are 1 to 31.
  - `billing_interval` 'BIMONTHLY' | 'BIWEEKLY' | 'BIYEARLY' | 'DAILY' | 'MONTHLY' | 'QUARTERLY' | 'SEMIYEARLY' | 'TRIYEARLY' | 'WEEKLY' | 'YEARLY' — How often the buyer is billed. The possible billing intervals are as follows: - `BIMONTHLY`: every 2 months - `BIWEEKLY`: every 2 weeks - `BIYEARLY`: every 2 years - `DAILY`: every day - `MONTHLY`: every month - `QUARTERLY`: each quarter - `SEMIYEARLY`: twice a year - `TRIYEARLY`: every 3 years - `WEEKLY`: every week - `YEARLY`: every year
  - `buyer_details` object — An object containing details about the buyer.
    - `identity_id` string — The [identity ID](/api/identities) of the buyer.
    - `instrument_id` unknown
    - `requested_delivery_methods` object[] — A list of requested delivery methods. Each method specifies the type of delivery and the destination(s) where the receipt should be sent.
      - `type` 'EMAIL' | 'SMS' | 'PRINT', required — The method of receipt delivery.
      - `destinations` string[], required — A list of destination addresses or identifiers where the receipt should be sent.
    - `shipping_address` Address
      - `line1` string, nullable, required — First line of the address (max 35 characters).
      - `line2` string, nullable — Second line of the address (max 35 characters).
      - `city` string, nullable, required — City (max 20 characters).
      - `region` string, nullable, required — 2-letter State code.
      - `postal_code` string, nullable, required — Zip or Postal code (max 7 characters).
      - `country` 'ABW' | 'AFG' | 'AGO' | 'AIA' | 'ALA' | 'ALB' | 'AND' | 'ARE' | 'ARG' | 'ARM' | 'ASM' | 'ATA' | 'ATF' | 'ATG' | 'AUS' | 'AUT' | 'AZE' | 'BDI' | 'BEL' | 'BEN' | 'BES' | 'BFA' | 'BGD' | 'BGR' | 'BHR' | 'BHS' | 'BIH' | 'BLM' | 'BLR' | 'BLZ' | 'BMU' | 'BOL' | 'BRA' | 'BRB' | 'BRN' | 'BTN' | 'BVT' | 'BWA' | 'CAF' | 'CAN' | 'CCK' | 'CHE' | 'CHL' | 'CHN' | 'CIV' | 'CMR' | 'COD' | 'COG' | 'COK' | 'COL' | 'COM' | 'CPV' | 'CRI' | 'CUB' | 'CUW' | 'CXR' | 'CYM' | 'CYP' | 'CZE' | 'DEU' | 'DJI' | 'DMA' | 'DNK' | 'DOM' | 'DZA' | 'ECU' | 'EGY' | 'ERI' | 'ESH' | 'ESP' | 'EST' | 'ETH' | 'FIN' | 'FJI' | 'FLK' | 'FRA' | 'FRO' | 'FSM' | 'GAB' | 'GBR' | 'GEO' | 'GGY' | 'GHA' | 'GIB' | 'GIN' | 'GLP' | 'GMB' | 'GNB' | 'GNQ' | 'GRC' | 'GRD' | 'GRL' | 'GTM' | 'GUF' | 'GUM' | 'GUY' | 'HKG' | 'HMD' | 'HND' | 'HRV' | 'HTI' | 'HUN' | 'IDN' | 'IMN' | 'IND' | 'IOT' | 'IRL' | 'IRN' | 'IRQ' | 'ISL' | 'ISR' | 'ITA' | 'JAM' | 'JEY' | 'JOR' | 'JPN' | 'KAZ' | 'KEN' | 'KGZ' | 'KHM' | 'KIR' | 'KNA' | 'KOR' | 'KWT' | 'LAO' | 'LBN' | 'LBR' | 'LBY' | 'LCA' | 'LIE' | 'LKA' | 'LSO' | 'LTU' | 'LUX' | 'LVA' | 'MAC' | 'MAF' | 'MAR' | 'MCO' | 'MDA' | 'MDG' | 'MDV' | 'MEX' | 'MHL' | 'MKD' | 'MLI' | 'MLT' | 'MMR' | 'MNE' | 'MNG' | 'MNP' | 'MRT' | 'MSR' | 'MTQ' | 'MUS' | 'MWI' | 'MYS' | 'MYT' | 'NAM' | 'NCL' | 'NER' | 'NFK' | 'NGA' | 'NIC' | 'NIU' | 'NLD' | 'NOR' | 'NPL' | 'NRU' | 'NZL' | 'OMN' | 'PAK' | 'PAN' | 'PCN' | 'PER' | 'PHL' | 'PLW' | 'PNG' | 'POL' | 'PRI' | 'PRK' | 'PRT' | 'PRY' | 'PSE' | 'PYF' | 'QAT' | 'REU' | 'ROU' | 'RUS' | 'RWA' | 'SAU' | 'SDN' | 'SEN' | 'SGP' | 'SGS' | 'SHN' | 'SJM' | 'SLB' | 'SLE' | 'SLV' | 'SMR' | 'SOM' | 'SPM' | 'SRB' | 'SSD' | 'STP' | 'SUR' | 'SVK' | 'SVN' | 'SWE' | 'SWZ' | 'SXM' | 'SYC' | 'SYR' | 'TCA' | 'TCD' | 'TGO' | 'THA' | 'TJK' | 'TKL' | 'TKM' | 'TLS' | 'TON' | 'TTO' | 'TUN' | 'TUR' | 'TUV' | 'TWN' | 'TZA' | 'UGA' | 'UKR' | 'UMI' | 'URY' | 'USA' | 'UZB' | 'VAT' | 'VCT' | 'VEN' | 'VGB' | 'VIR' | 'VNM' | 'VUT' | 'WLF' | 'WSM' | 'XKX' | 'YEM' | 'ZAF' | 'ZMB' | 'ZWE', nullable, required
  - `canceled_via` 'MERCHANT' | 'AUTOMATED_OVERDUE' | 'SUPPORT', nullable — If the subscription was canceled, this field shows how the cancellation was initiated. Possible values: - `MERCHANT` - The customer (merchant) canceled the subscription themselves. The `linked_to` field indicates the related `Merchant`. - `AUTOMATED_OVERDUE` - The subscription was canceled by the overdue system. - `SUPPORT` - The subscription was canceled by Finix Support.
  - `currency` 'USD' | 'CAD' — ISO 4217 3-letter currency code.
  - `expires_at` string, date-time — The date-time that the `Subscription` expires if `total_billing_intervals` is set for the `Subscription`.
  - `first_charge_at` string, date-time — Timestamp when the first [Transfer](/api/transfers) will occur.
  - `linked_to` string — The ID of the [Merchant](/api/merchants) resource that you wish to link to the `Subscription` (i.e., the merchant that the subscription belongs to). At this time, only approved merchants with one of the following processors are valid: - `DUMMY_V1` - `FINIX_V1`
  - `linked_type` 'MERCHANT' — The type of the resource that is specified in the `linked_to` field.
  - `next_billing_date` object — Details when the next [Transfer](/api/transfers) will occur.
    - `year` integer — The year the next `Transfer` will occur.
    - `month` integer — The month the next `Transfer` will occur.
    - `day` integer — The day the next `Transfer` will occur.
  - `nickname` string — A human-readable name for the resource.
  - `start_subscription_at` string, date-time — Indicates that the subscription is scheduled to begin in the future. The timestamp specifies the exact start date for subscription billing.
  - `state` 'ACTIVE' | 'CANCELED' | 'EXPIRED' | 'NOT_STARTED' | 'PAST_DUE' — The state of the `Subscription`. - The `NOT_STARTED` state occurs when the subscription has not yet started, typically indicated by a `start_subscription_at` timestamp set during creation. - A subscription in the `PAST_DUE` state is unpaid but has not yet been canceled.
  - `subscription_details` object — An object containing subscription details.
    - `collection_method` 'BILL_AUTOMATICALLY', required — The method by which subscription payments are collected. Currently, automatic billing of the `Payment Instrument` is the only available method.
    - `send_invoice` boolean — Whether to send the user an invoice.
    - `send_receipt` boolean — Whether to send the user a receipt.
    - `trial_details` object — Object containing trial details.
      - `interval_type` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' — The unit of time for the trial period.
      - `interval_count` integer — The number of intervals of `interval_type` used to describe the duration of the trial.
      - `trial_started_at` string, date-time, nullable — A timestamp indicating when the trial period began.
      - `trial_expected_start_at` string, date-time — A timestamp indicating when the trial period is expected to start.
      - `trial_expected_end_at` string, date-time — A timestamp indicating when the trial period ends.
    - `discount_phase_details` object — Object containing discount phase details.
      - `amount` integer — The discounted amount (in cents) that the buyer is charged during the discount phase.
      - `billing_interval_count` integer — The number of billing intervals the discount applies. After this period, the buyer is charged the full `amount` from the `Subscription`.
      - `discount_phase_started_at` string, date-time, nullable — A timestamp indicating when the discount phase began.
      - `discount_phase_expected_start_at` string, date-time — A timestamp indicating when the discount phase is expected to start.
      - `discount_phase_expected_end_at` string, date-time — A timestamp indicating when the discount phase is expected to end.
    - `notification_preferences` object — Object containing notification preferences.
      - `send_confirmation` boolean — Whether to send a confirmation email to the user.
  - `subscription_link_id` string, nullable — The ID of the `Subscription Link` that created the `Subscription`.
  - `subscription_phase` 'EVERGREEN' | 'DISCOUNT' | 'FIXED' | 'NONE' | 'TRIAL' — Indicates the period within a subscription where specific rules apply. - `EVERGREEN` - The buyer is billed continuously for the subscription until the subscription is canceled. - `DISCOUNT` - The buyer receives a discounted price for a limited billing interval, after which the customer is charged the full subscription amount. - `FIXED` state - Applicable to fixed-length subscriptions. - `NONE` - Indicates that when the `start_subscription_at` timestamp is set during subscription creation, the subscription is not yet in any phase, and billing has not started. - `TRIAL` - The period during which the buyer is not billed; after this phase, the buyer will begin being billed.
  - `subscription_plan_id` string — The ID of a [Subscription Plan](/api/subscription-plans) from which this `Subscription` was created. When provided, the plan's `amount`, `billing_interval`, and other defaults are inherited.
  - `tags` Tags, nullable — Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`)
  - `total_billing_intervals` integer — The total number of billing intervals for the `Subscription`. This represents the total count of recurring billing cycles, such as months or weeks, depending on the billing frequency.
  - `_links` object — An object containing link(s) relevant to the request. You can store these links for follow-up requests.
    - `self` Self — Link to the resource that was used in the request.
      - `href` string

## Other responses

- `400` — Bad Request. The server cannot process the request due to malformed syntax or invalid data.
- `401` — Unauthorized. Authentication is required and has failed or has not been provided.
- `403` — Forbidden. The client is authenticated but does not have permission to access the resource.
- `404` — Not Found. The requested resource could not be found on the server.
- `406` — Not Acceptable. The server could not accept the submitted request. Confirm how the request was formatted and submitted.

---

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