> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a subscription

> 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.

**`v2`** · Base URL `https://api.fintoc.com/v2`


## OpenAPI

````yaml reference/fintoc-api-v2.json PATCH /subscriptions/{id}
openapi: 3.1.0
info:
  title: fintoc-api-v2
  version: v2026-02-01
servers:
  - url: https://api.fintoc.com/v2
security: []
paths:
  /subscriptions/{id}:
    patch:
      tags:
        - Subscriptions
      summary: Update a subscription
      description: >-
        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.
      operationId: subscriptions-update
      parameters:
        - name: id
          in: path
          description: The `id` of the subscription to update.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                trial_end:
                  type: string
                  format: date-time
                  description: >-
                    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.
                  example: '2026-07-01T15:00:00Z'
                payment_method:
                  type: string
                  description: >-
                    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`.
                  example: pm_2c4mDhAbCdEfGhIjKlMnOpQrStu
              anyOf:
                - required:
                    - trial_end
                - required:
                    - payment_method
            examples:
              update_subscription_trial_end:
                summary: Extend the trial period
                value:
                  trial_end: '2026-07-01T15:00:00Z'
              update_subscription_payment_method:
                summary: Swap the payment method
                value:
                  payment_method: pm_2c4mDhAbCdEfGhIjKlMnOpQrStu
      responses:
        '200':
          description: >-
            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.
          content:
            application/json:
              examples:
                subscription_updated:
                  value:
                    id: sub_2c4mDcMaVxDx7nT3o5GbPMQbS2v
                    object: subscription
                    billing_cycle_anchor: '2026-07-01T15:00:00Z'
                    collection_method: send_invoice
                    created_at: '2026-06-01T15:00:00Z'
                    customer: cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu
                    items:
                      - id: si_2c4mDfkPLLrLTCJ3wPCEHGYpkVf
                        object: subscription_item
                        price:
                          currency: CLP
                          product:
                            id: prod_2c4mDgwQqkNwMHnXSc4DBjkbcWz
                            object: product
                            created_at: '2026-06-01T15:00:00Z'
                            description: Access to every premium feature.
                            image_url: https://example.com/image.png
                            metadata: {}
                            mode: live
                            name: Premium plan
                          recurring:
                            interval: month
                            interval_count: 1
                          unit_amount: 10000
                        quantity: 1
                    metadata:
                      internal_id: '12345'
                    mode: live
                    payment_method: null
                    status: trialing
                    trial_end: '2026-07-01T15:00:00Z'
                subscription_payment_method_swapped:
                  value:
                    id: sub_2c4mDcMaVxDx7nT3o5GbPMQbS2v
                    object: subscription
                    billing_cycle_anchor: '2026-06-01T15:00:00Z'
                    collection_method: send_invoice
                    created_at: '2026-06-01T15:00:00Z'
                    customer: cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu
                    items:
                      - id: si_2c4mDfkPLLrLTCJ3wPCEHGYpkVf
                        object: subscription_item
                        price:
                          currency: CLP
                          product:
                            id: prod_2c4mDgwQqkNwMHnXSc4DBjkbcWz
                            object: product
                            created_at: '2026-06-01T15:00:00Z'
                            description: Access to every premium feature.
                            image_url: https://example.com/image.png
                            metadata: {}
                            mode: live
                            name: Premium plan
                          recurring:
                            interval: month
                            interval_count: 1
                          unit_amount: 10000
                        quantity: 1
                    metadata:
                      internal_id: '12345'
                    mode: live
                    payment_method: pm_2c4mDhAbCdEfGhIjKlMnOpQrStu
                    status: active
                    trial_end: null
              schema:
                $ref: '#/components/schemas/subscription'
        '400':
          description: >-
            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.
          content:
            application/json:
              examples:
                missing_params:
                  value:
                    error:
                      type: invalid_request_error
                      code: missing_parameter
                      param: trial_end
                      message: >-
                        You must provide at least one of trial_end or
                        payment_method
                      doc_url: https://docs.fintoc.com/reference/errors
                invalid_trial_end:
                  value:
                    error:
                      type: invalid_request_error
                      code: invalid_date
                      param: trial_end
                      message: >-
                        Invalid date: not-a-date. You need to provide a date in
                        ISO 8601 format (YYYY-MM-DD)
                      doc_url: https://docs.fintoc.com/reference/errors
              schema:
                $ref: '#/components/schemas/error_object'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              examples:
                invalid_api_key:
                  value:
                    error:
                      type: authentication_error
                      code: invalid_api_key
                      message: 'Invalid API Key: invalid-*oken'
              schema:
                $ref: '#/components/schemas/error_object'
        '404':
          description: >-
            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.
          content:
            application/json:
              examples:
                subscription_not_found:
                  value:
                    error:
                      type: invalid_request_error
                      code: missing_resource
                      param: id
                      message: >-
                        No such invoicing/subscription:
                        sub_2c4mDcMaVxDx7nT3o5GbPMQbS2v
                      doc_url: https://docs.fintoc.com/reference/errors
                payment_method_not_found:
                  value:
                    error:
                      type: invalid_request_error
                      code: missing_resource
                      message: 'No such payment_method: pm_2c4mDhAbCdEfGhIjKlMnOpQrStu'
                      doc_url: https://docs.fintoc.com/reference/errors
              schema:
                $ref: '#/components/schemas/error_object'
        '409':
          description: >-
            The subscription cannot be updated in its current state, for example
            because it is canceled.
          content:
            application/json:
              examples:
                subscription_not_editable:
                  value:
                    error:
                      type: invalid_request_error
                      code: subscription_not_editable
                      message: Subscription can not be edited in its current state
              schema:
                $ref: '#/components/schemas/error_object'
        '422':
          description: >-
            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`.
          content:
            application/json:
              examples:
                payment_method_inactive:
                  value:
                    error:
                      type: invalid_request_error
                      code: payment_method_inactive
                      message: >-
                        Payment method is not active:
                        pm_2c4mDhAbCdEfGhIjKlMnOpQrStu
                      doc_url: https://docs.fintoc.com/reference/errors
                payment_method_type_not_supported:
                  value:
                    error:
                      type: invalid_request_error
                      code: payment_method_type_not_supported
                      message: >-
                        Payment method type not supported for subscriptions:
                        bank_transfer
                      doc_url: https://docs.fintoc.com/reference/errors
              schema:
                $ref: '#/components/schemas/error_object'
      security:
        - api_key: []
components:
  schemas:
    subscription:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the subscription.
          example: sub_2c4mDcMaVxDx7nT3o5GbPMQbS2v
        object:
          const: subscription
          description: Type of the object. Always `subscription`.
        billing_cycle_anchor:
          type: string
          format: date-time
          description: >-
            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.
          example: '2026-06-01T15:00:00Z'
        collection_method:
          type: string
          enum:
            - charge_automatically
            - send_invoice
          description: >-
            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`.
          example: send_invoice
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the subscription was created.
          example: '2026-06-01T15:00:00Z'
        customer:
          type: string
          description: ID of the customer the subscription bills.
          example: cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu
        items:
          type: array
          items:
            $ref: '#/components/schemas/subscription_item'
          description: Items the subscription bills for on every billing cycle.
        metadata:
          type: object
          description: Set of key-value pairs attached to the subscription.
          example:
            order_id: '12345'
        mode:
          type: string
          enum:
            - live
            - test
          description: >-
            Mode of the object. One of `live` or `test`. `test` subscriptions
            use fake data for integration testing and do not collect real money.
          example: live
        payment_method:
          type:
            - string
            - 'null'
          description: >-
            ID of the payment method charged when `collection_method` is
            `charge_automatically`. Always `null` for subscriptions created
            through the API.
          example: null
        status:
          type: string
          enum:
            - active
            - canceled
            - incomplete
            - trialing
          description: >-
            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).
          example: active
        trial_end:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            ISO 8601 timestamp at which the trial period ends, or `null` if the
            subscription has no trial.
          example: null
      required:
        - id
        - object
        - billing_cycle_anchor
        - collection_method
        - created_at
        - customer
        - items
        - metadata
        - mode
        - payment_method
        - status
        - trial_end
    error_object:
      type: object
      properties:
        error:
          type: object
          description: Details of the error that caused the request to fail.
          properties:
            code:
              type: string
              description: >-
                Machine-readable code identifying the specific error, for
                example `invalid_api_key`. Not returned by every error.
              example: invalid_api_key
            doc_url:
              type: string
              description: >-
                URL of a documentation page with more details about the error.
                Not returned by every error.
              example: https://docs.fintoc.com/reference/errors
            message:
              type: string
              description: Human-readable message describing the error.
              example: 'Invalid API Key: invalid-*oken'
            param:
              type:
                - string
                - 'null'
              description: >-
                Name of the request parameter that caused the error. `null` when
                the error cannot be tied to a single parameter, and not returned
                by every error.
              example: amount
            type:
              type: string
              description: >-
                Category of the error, for example `invalid_request_error`,
                `authentication_error`, or `api_error`.
              example: invalid_request_error
          required:
            - type
            - message
    subscription_item:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the subscription item.
          example: si_2c4mDfkPLLrLTCJ3wPCEHGYpkVf
        object:
          const: subscription_item
          description: Type of the object. Always `subscription_item`.
        price:
          type: object
          description: Price the item bills for on every billing cycle.
          properties:
            currency:
              type: string
              enum:
                - CLF
                - CLP
                - MXN
              description: >-
                Three-letter ISO 4217 currency code, returned in uppercase. One
                of `CLP`, `MXN` or `CLF`.
              example: CLP
            product:
              type: object
              description: Product the price belongs to.
              properties:
                id:
                  type: string
                  description: Unique identifier of the product.
                  example: prod_2c4mDgwQqkNwMHnXSc4DBjkbcWz
                object:
                  const: product
                  description: Type of the object. Always `product`.
                created_at:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp of when the product was created.
                  example: '2026-06-01T15:00:00Z'
                description:
                  type:
                    - string
                    - 'null'
                  description: Free-text description of the product.
                  example: Access to every premium feature.
                image_url:
                  type:
                    - string
                    - 'null'
                  description: HTTPS URL of an image of the product.
                  example: https://example.com/image.png
                metadata:
                  type: object
                  description: Set of key-value pairs attached to the product.
                  example:
                    category: saas
                mode:
                  type: string
                  enum:
                    - live
                    - test
                  description: >-
                    Mode of the object. One of `live` or `test`. `test` products
                    use fake data for integration testing.
                  example: live
                name:
                  type: string
                  description: Name of the product.
                  example: Premium plan
              required:
                - id
                - object
                - created_at
                - description
                - image_url
                - metadata
                - mode
                - name
            recurring:
              type: object
              description: Billing cadence of the price.
              properties:
                interval:
                  type: string
                  enum:
                    - month
                    - year
                  description: >-
                    Frequency at which the price bills. One of `month` or
                    `year`.
                  example: month
                interval_count:
                  type: integer
                  description: >-
                    Number of intervals between each billing cycle. For example,
                    `interval: "month"` with `interval_count: 3` bills every 3
                    months.
                  example: 1
              required:
                - interval
                - interval_count
            unit_amount:
              type: integer
              description: >-
                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.
              example: 10000
          required:
            - currency
            - product
            - recurring
            - unit_amount
        quantity:
          type: integer
          description: Number of units of the price the item bills for.
          example: 1
      required:
        - id
        - object
        - price
        - quantity
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header

````