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

# Update a subscription

> Updates an existing subscription to a new plan, charge period, and/or features. Set `paymentBehavior` to `activate_on_payment` when the change should take effect only after payment succeeds.

> **Warning:** Free plans are created as one-time charges. Upgrading from a free plan is not supported via this endpoint. Use the [Create Checkout Session](/api-reference/checkout/create-a-checkout-session) endpoint instead.

<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>


## OpenAPI

````yaml /api-reference/openapi.json post /subscriptions/{subscriptionId}/update/
openapi: 3.0.0
info:
  title: kelviq API
  version: 1.0.0
  description: >-
    API for interacting with kelviq services, derived from Python SDK
    documentation.
servers:
  - url: https://sandboxapi.kelviq.com/api/v1
    description: Sandbox — Test payments
  - url: https://api.kelviq.com/api/v1
    description: Production — Live payments
security:
  - bearerAuth: []
tags:
  - name: Products
    description: Catalog products.
  - name: Product Settings
    description: Per-product settings (currency, VPN/Tor/proxy, product URL).
  - name: Product Files
    description: Product images and downloadable assets.
  - name: Features
    description: Catalog features that can be granted as plan entitlements.
  - name: Plans
    description: Catalog plans (CRUD, publish, versions, prices).
  - name: Plan Entitlements
    description: Feature entitlements attached to a plan.
  - name: Plan Files
    description: Files attached to plans, and signed download links.
  - name: Media
    description: Generate presigned S3 upload URLs for product/plan images and files.
  - name: Partner
    description: Partner integration APIs (organization provisioning, lookup).
  - name: Charges
    description: >-
      One-time payments charged immediately against a customer's default payment
      method.
  - name: Refunds
    description: Full and partial refunds for paid orders.
  - name: Payment Methods
    description: Saved customer payment methods (cards, etc.).
paths:
  /subscriptions/{subscriptionId}/update/:
    post:
      tags:
        - Subscriptions
      summary: Update a subscription
      description: >-
        Updates an existing subscription to a new plan, charge period, and/or
        features. Set `paymentBehavior` to `activate_on_payment` when the change
        should take effect only after payment succeeds.


        > **Warning:** Free plans are created as one-time charges. Upgrading
        from a free plan is not supported via this endpoint. Use the [Create
        Checkout Session](/api-reference/checkout/create-a-checkout-session)
        endpoint instead.
      operationId: updateSubscription
      parameters:
        - name: subscriptionId
          in: path
          required: true
          description: >-
            The unique identifier of the subscription to be updated. Example
            UUID from docs: 78058918-9746-4280-9b9b-1bd5115eec6e
          example: 78058918-9746-4280-9b9b-1bd5115eec6e
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSubscriptionRequest'
      responses:
        '200':
          description: UUID of the updated subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateSubscriptionResponse'
              example:
                subscriptionId: dffaf07e-4517-47db-ba3a-59a05aa2d465
components:
  schemas:
    UpdateSubscriptionRequest:
      type: object
      required:
        - planIdentifier
        - chargePeriod
      properties:
        planIdentifier:
          type: string
          description: The identifier of the new plan.
          example: new_plan_enterprise
        chargePeriod:
          type: string
          enum:
            - ONE_TIME
            - MONTHLY
            - YEARLY
            - WEEKLY
            - DAILY
            - TWENTY_EIGHT_DAYS
            - THREE_MONTHS
            - SIX_MONTHS
          description: The new charging period for the subscription.
          example: YEARLY
        features:
          type: array
          items:
            $ref: '#/components/schemas/FeatureInput'
          nullable: true
          description: List of features and quantities to update for the subscription.
          example:
            - identifier: seats
              quantity: 10
        ipAddress:
          type: string
          nullable: true
          description: The IP Address of the customer, for location-based pricing.
          example: 103.154.35.20
        trialEnd:
          type: string
          nullable: true
          description: >-
            Controls the trial period for the updated subscription. Accepts
            either the literal string `"now"` to end any active trial
            immediately, or an ISO 8601 datetime string (e.g. `"2027-12-31
            23:59:59"`) to set a new trial end date. The datetime must be in the
            future. If omitted, the existing trial behavior is preserved.
          example: '2027-12-31 23:59:59'
        paymentBehavior:
          type: string
          enum:
            - activate_on_payment
          nullable: true
          description: >-
            Controls when a paid subscription update takes effect. Set to
            `"activate_on_payment"` to keep the current subscription active
            while payment is pending and apply the new plan, charge period, and
            features only after payment succeeds. If payment is not completed,
            the pending update expires and the current subscription remains
            unchanged. If omitted, the update uses the default immediate
            behavior.
          example: activate_on_payment
    UpdateSubscriptionResponse:
      type: object
      properties:
        subscriptionId:
          type: string
          example: dffaf07e-4517-47db-ba3a-59a05aa2d465
    FeatureInput:
      type: object
      required:
        - identifier
        - quantity
      properties:
        identifier:
          type: string
          description: The unique identifier for the feature.
          example: seats
        quantity:
          type: integer
          description: The desired quantity for this feature.
          example: 5
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        The Server API Key obtained from the kelviq application. Pass as a
        Bearer token in the Authorization header. Example: 'Authorization:
        Bearer __YOUR_API_KEY__'

````