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

# Preview Subscription Update

> Preview a subscription upgrade or downgrade before confirming it. The target price must be a recurring price owned by the current merchant and must support the subscription payment currency. Use immediate to request an immediate or period-end update, or omit it to let the system decide. billingCycleAnchor and prorationBehavior may only be supplied with immediate=true. The preview returns the effective billing options when applicable. See the subscription guide for billing combinations and free-trial restrictions.



## OpenAPI

````yaml POST /subscription/{id}/update/preview
openapi: 3.1.0
info:
  title: Clink API
  description: >-
    Official API documentation for Clink's payment processing platform. This API
    enables merchants to create and manage payment sessions, handle
    subscriptions, and process transactions.
  version: 1.0.0
servers:
  - url: https://uat-api.clinkbill.com/api/
security:
  - ApiKeyAuth: []
paths:
  /subscription/{id}/update/preview:
    post:
      tags:
        - Subscription API
      summary: Preview Subscription Update
      description: >-
        Preview a subscription upgrade or downgrade before confirming it. The
        target price must be a recurring price owned by the current merchant and
        must support the subscription payment currency. Use immediate to request
        an immediate or period-end update, or omit it to let the system decide.
        billingCycleAnchor and prorationBehavior may only be supplied with
        immediate=true. The preview returns the effective billing options when
        applicable. See the subscription guide for billing combinations and
        free-trial restrictions.
      operationId: previewSubscriptionUpdate
      parameters:
        - $ref: '#/components/parameters/TimestampHeader'
        - name: id
          in: path
          description: Unique identifier of the subscription
          required: true
          schema:
            type: string
      requestBody:
        description: Subscription update preview request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionUpdatePreviewApiRequest'
            examples:
              previewImmediateUpgradeWithoutProration:
                summary: Preview an immediate upgrade without proration
                value:
                  priceId: price_xxxx
                  quantity: 1
                  promotionCode: SUMMER25
                  immediate: true
                  billingCycleAnchor: now
                  prorationBehavior: none
              previewUpgradeWithBillingCycleReset:
                summary: Preview an immediate upgrade with a new billing cycle
                value:
                  priceId: price_xxxx
                  quantity: 1
                  promotionCode: SUMMER25
                  immediate: true
                  billingCycleAnchor: now
                  prorationBehavior: always_invoice
              previewPeriodEndUpdate:
                summary: Preview a period-end update
                value:
                  priceId: price_xxxx
                  quantity: 1
                  promotionCode: SUMMER25
                  immediate: false
              previewUpgrade:
                summary: Preview an upgrade
                value:
                  priceId: price_xxxx
                  quantity: 1
                  promotionCode: SUMMER25
        required: true
      responses:
        '200':
          description: Subscription update preview returned successfully
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SubscriptionUpdatePreviewApiResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionUpdatePreviewApiResponse'
              examples:
                immediateUpgrade:
                  summary: Immediate upgrade preview
                  value:
                    code: 200
                    msg: success
                    data:
                      subscriptionId: sub_xxxxx
                      immediate: true
                      billingCycleAnchor: unchanged
                      prorationBehavior: always_invoice
                      recurringPrice:
                        periodStart: 1752654041000
                        periodEnd: 1755332441000
                        priceId: price_xxxx
                        priceSnapshotId: priceSnapshotId_xxxx
                        productId: prod_xxxx
                        productName: Pro Plan
                        totalAmount: 49.99
                        unitAmount: 49.99
                        currencySymbol: $
                        currency: USD
                        quantity: 1
                        interval: month
                        recurring: '{"interval":"month","pricingModel":"flat_rate"}'
                      lines:
                        proratedCredit:
                          productName: Starter Plan
                          totalAmount: 9.99
                          currencySymbol: $
                          currency: USD
                          quantity: 1
                        proratedCharge:
                          productName: Pro Plan
                          totalAmount: 49.99
                          currencySymbol: $
                          currency: USD
                          quantity: 1
                        periodStart: 1752654041000
                        periodEnd: 1755332441000
                        subtotalAmount: 40
                        taxAmount: 0
                        taxRate: 0
                        taxName: Sales Tax
                        totalAmount: 40
                        currencySymbol: $
                        currency: USD
                      discountObject:
                        couponId: cpn_xxxxx
                        couponName: Summer Promotion
                        couponTerms: 25% off
                        promotionCode: SUMMER25
                        discountAmount: 10
                        durationType: once
                        durationMonths: 1
                        couponUsedTimes: 0
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                type: string
components:
  parameters:
    TimestampHeader:
      name: X-Timestamp
      in: header
      required: true
      description: >-
        Current timestamp in milliseconds since Unix epoch (required for request
        signing)
      schema:
        type: string
        example: '1783513683000'
  schemas:
    SubscriptionUpdatePreviewApiRequest:
      required:
        - priceId
      type: object
      description: Parameters required to preview a subscription upgrade or downgrade.
      allOf:
        - if:
            properties:
              immediate:
                const: true
            required:
              - immediate
          else:
            properties:
              billingCycleAnchor:
                type: 'null'
              prorationBehavior:
                type: 'null'
      properties:
        quantity:
          type: integer
          minimum: 1
          default: 1
          description: >-
            Number of units for the target price. Optional; defaults to 1 when
            omitted. null and values below 1 are invalid.
        priceId:
          type: string
          description: >-
            Target recurring price ID. The price must belong to the current
            merchant and support the subscription payment currency.
        promotionCode:
          type: string
          description: Promotion code to apply to the updated subscription.
        immediate:
          type:
            - boolean
            - 'null'
          description: >-
            Whether to force the update to take effect immediately. true
            requests an immediate update; false schedules it for the end of the
            current billing or trial period. Omitted or null lets the system
            decide. Explicit true requires both current and target prices to use
            flat_rate pricing. Outside a free trial, the target full-cycle
            amount (unit amount multiplied by quantity) must be greater than the
            current full-cycle amount; immediate downgrades and equal-amount
            changes are rejected.
          example: true
        billingCycleAnchor:
          type:
            - string
            - 'null'
          description: >-
            Billing cycle anchor for an immediate update. A non-null value
            requires immediate=true. now starts a new full billing cycle at the
            update time; unchanged preserves the current period end. Outside a
            free trial, omitted or null uses unchanged. For an immediate
            free-trial update, omit this field if the target still has trial
            time remaining; when switching directly to paid billing, only now or
            omitted/null is allowed, and now is used.
          enum:
            - now
            - unchanged
            - null
          example: now
        prorationBehavior:
          type:
            - string
            - 'null'
          description: >-
            Proration policy for an immediate update. A non-null value requires
            immediate=true. always_invoice credits the unused portion of the
            current plan and charges the target plan for the remaining period
            with unchanged, or a full cycle with now. none gives no credit for
            the current plan and charges the target plan's full-cycle amount
            with either anchor; it does not waive payment. Discounts and tax are
            applied afterward. Outside a free trial, omitted or null uses
            always_invoice. For an immediate free-trial update, omit this field
            if the target still has trial time remaining; when switching
            directly to paid billing, only none or omitted/null is allowed, and
            none is used.
          enum:
            - always_invoice
            - none
            - null
          example: always_invoice
    SubscriptionUpdatePreviewApiResponse:
      type: object
      properties:
        code:
          type: integer
          description: Response status code, 200 when success
          format: int32
          example: 200
        msg:
          type: string
          example: success
          description: Brief description of what happened, 'success' when happy case
        data:
          $ref: '#/components/schemas/SubscriptionUpdatePreviewApiVo'
    SubscriptionUpdatePreviewApiVo:
      type: object
      description: Preview result for a subscription upgrade or downgrade.
      properties:
        subscriptionId:
          type: string
          description: Unique identifier of the subscription
        immediate:
          type: boolean
          description: >-
            Whether the update takes effect immediately. false means the update
            is scheduled for the next billing period boundary.
        billingCycleAnchor:
          type:
            - string
            - 'null'
          description: >-
            Effective billing cycle anchor. Populated for immediate updates
            outside a free trial, or as now when a free-trial update starts paid
            billing with a positive charge before discounts. Not populated for
            deferred updates or free-trial updates without a charge. now starts
            a new full billing cycle; unchanged preserves the current period
            end.
          enum:
            - now
            - unchanged
            - null
          example: unchanged
        prorationBehavior:
          type:
            - string
            - 'null'
          description: >-
            Effective proration policy. Populated for immediate updates outside
            a free trial, or as none when a free-trial update starts paid
            billing with a positive charge before discounts. Not populated for
            deferred updates or free-trial updates without a charge.
            always_invoice applies proration; none charges the target plan's
            full-cycle amount without credit for the current plan, before
            discounts and tax.
          enum:
            - always_invoice
            - none
            - null
          example: always_invoice
        recurringPrice:
          $ref: '#/components/schemas/SubscriptionUpdateRecurringPriceApiVo'
          description: Target recurring price after the update.
        lines:
          $ref: '#/components/schemas/SubscriptionUpdateLineDataApiVo'
          description: Billing preview for the update.
        discountObject:
          $ref: '#/components/schemas/SubscriptionUpdateDiscountApiVo'
          description: Discount applied to the update, if any.
    SubscriptionUpdateRecurringPriceApiVo:
      type: object
      description: Target recurring price details for a subscription update.
      properties:
        periodStart:
          type: integer
          description: >-
            Unix timestamp in milliseconds when the target recurring period
            starts.
          format: int64
        periodEnd:
          type: integer
          description: >-
            Unix timestamp in milliseconds when the target recurring period
            ends.
          format: int64
        priceId:
          type: string
          description: Target recurring price ID.
        priceSnapshotId:
          type: string
          description: Target recurring price snapshot ID used when confirming the update.
        productId:
          type: string
          description: Target product ID.
        productName:
          type: string
          description: Target product name.
        totalAmount:
          type: number
          description: Total recurring amount for the target price and quantity.
        unitAmount:
          type: number
          description: Unit amount for the target price.
        currencySymbol:
          type: string
          description: Display symbol for the currency.
        currency:
          type: string
          description: Currency used by the subscription update.
          enum:
            - USD
            - EUR
            - JPY
            - GBP
            - AUD
            - CAD
            - CNY
            - HKD
            - SGD
            - KRW
            - AED
            - THB
            - IDR
            - PHP
            - MYR
            - BRL
            - INR
        quantity:
          type: integer
          description: Target quantity.
          format: int32
        interval:
          type: string
          description: Billing interval for the target recurring price.
          enum:
            - day
            - week
            - month
            - year
            - quarter
            - half_year
            - custom
        recurring:
          type: string
          description: Raw recurring configuration snapshot for the target price.
    SubscriptionUpdateLineDataApiVo:
      type: object
      description: Billing line preview for a subscription update.
      properties:
        proratedCredit:
          $ref: '#/components/schemas/SubscriptionUpdateLineDataPriceApiVo'
          description: >-
            Credit for unused time on the current plan. Present for immediate
            updates when applicable.
        proratedCharge:
          $ref: '#/components/schemas/SubscriptionUpdateLineDataPriceApiVo'
          description: >-
            Target-plan charge before discounts and tax for an immediate update.
            With always_invoice and unchanged, this is prorated for the
            remaining billing period. With now or none, this is the target
            plan's full-cycle amount. Free-trial updates charge a full cycle
            when switching directly to paid billing, or zero when trial time
            remains.
        periodStart:
          type: integer
          description: Unix timestamp in milliseconds when the billed period starts.
          format: int64
        periodEnd:
          type: integer
          description: Unix timestamp in milliseconds when the billed period ends.
          format: int64
        subtotalAmount:
          type: number
          description: Subtotal amount before tax.
        taxAmount:
          type: number
          description: Tax amount for the update.
        taxRate:
          type: number
          description: Tax rate applied to the update.
        taxName:
          type: string
          description: Tax name applied to the update.
        totalAmount:
          type: number
          description: Total amount after tax.
        currencySymbol:
          type: string
          description: Display symbol for the currency.
        currency:
          type: string
          description: Currency used by the subscription update.
          enum:
            - USD
            - EUR
            - JPY
            - GBP
            - AUD
            - CAD
            - CNY
            - HKD
            - SGD
            - KRW
            - AED
            - THB
            - IDR
            - PHP
            - MYR
            - BRL
            - INR
    SubscriptionUpdateDiscountApiVo:
      type: object
      description: Discount applied to a subscription update.
      properties:
        couponId:
          type: string
          description: Coupon ID.
        couponName:
          type: string
          description: Coupon name.
        couponTerms:
          type: string
          description: Human-readable coupon terms.
        promotionCode:
          type: string
          description: Promotion code applied to the update.
        discountAmount:
          type: number
          description: Discount amount applied to the update.
        durationType:
          type: string
          description: Discount duration type.
        durationMonths:
          type: integer
          description: Number of months the discount applies, when applicable.
          format: int32
        couponUsedTimes:
          type: integer
          description: Number of times the coupon has already been used.
          format: int32
    SubscriptionUpdateLineDataPriceApiVo:
      type: object
      description: Proration line amount for a subscription update.
      properties:
        productName:
          type: string
          description: Product name for this line.
        totalAmount:
          type: number
          description: Total amount for this line.
        currencySymbol:
          type: string
          description: Display symbol for the currency.
        currency:
          type: string
          description: Currency used by this line.
          enum:
            - USD
            - EUR
            - JPY
            - GBP
            - AUD
            - CAD
            - CNY
            - HKD
            - SGD
            - KRW
            - AED
            - THB
            - IDR
            - PHP
            - MYR
            - BRL
            - INR
        quantity:
          type: integer
          description: Quantity for this line.
          format: int32
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        Your secret API key obtained from the Clink dashboard (Developers
        section)

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.