> ## 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 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. ## 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. 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: previewUpgrade: summary: Preview an upgrade value: priceId: price_xxxx 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 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 - quantity type: object description: Parameters required to preview a subscription upgrade or downgrade. properties: 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. 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. 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: >- Charge for remaining time on the target plan. Present for immediate updates when applicable. 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) ````