> ## 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. # 确认订阅升降级 > Confirm a subscription upgrade or downgrade using the target price snapshot returned by the preview API. Immediate updates may require payment; period-end updates return success when no immediate payment is required. ## OpenAPI ````yaml POST /subscription/{id}/update/confirm 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/confirm: post: tags: - Subscription API summary: Confirm Subscription Update description: >- Confirm a subscription upgrade or downgrade using the target price snapshot returned by the preview API. Immediate updates may require payment; period-end updates return success when no immediate payment is required. operationId: confirmSubscriptionUpdate parameters: - $ref: '#/components/parameters/TimestampHeader' - name: id in: path description: Unique identifier of the subscription required: true schema: type: string requestBody: description: Subscription update confirmation request content: application/json: schema: $ref: '#/components/schemas/SubscriptionUpdateConfirmApiRequest' examples: confirmUpgrade: summary: Confirm an upgrade value: priceSnapshotId: priceSnapshotId_xxxx promotionCode: SUMMER25 required: true responses: '200': description: Subscription update confirmed successfully content: '*/*': schema: $ref: '#/components/schemas/SubscriptionUpdateConfirmApiResponse' application/json: schema: $ref: '#/components/schemas/SubscriptionUpdateConfirmApiResponse' examples: confirmedUpgrade: summary: Confirmed upgrade value: code: 200 msg: success data: subscriptionId: sub_xxxxx status: 1 code: success message: success subscription: subscriptionId: sub_xxxxx customerId: cus_xxxxx productId: prod_xxxx priceId: price_xxxx priceSnapshotId: priceSnapshotId_xxxx quantity: 1 paymentMethodType: CARD paymentInstrumentId: pi_xxxxx status: active billing: charge_automatically currency: USD currentPeriodStart: 1752654041000 currentPeriodEnd: 1755332441000 '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: SubscriptionUpdateConfirmApiRequest: required: - priceSnapshotId - quantity type: object description: Parameters required to confirm a subscription upgrade or downgrade. properties: priceSnapshotId: type: string description: Target price snapshot ID returned by the preview API. promotionCode: type: string description: Promotion code to apply to the updated subscription. SubscriptionUpdateConfirmApiResponse: 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/SubscriptionUpdateConfirmApiVo' SubscriptionUpdateConfirmApiVo: type: object description: Result returned after confirming a subscription update. properties: subscriptionId: type: string description: Unique identifier of the subscription. status: type: integer format: int32 description: >- Payment result status. `1` means success, `2` means pending, `3` means failure, and `5` means need next action to complete payment. enum: - 1 - 2 - 3 - 5 code: type: string description: Payment channel response code. declinedCode: type: string description: Payment declined code, when available. message: type: string description: Payment result message. action: $ref: '#/components/schemas/Action' description: >- Next action required to complete payment when status is `5` (NEXT_ACTION). subscription: $ref: '#/components/schemas/SubscriptionApiData' description: Subscription details after the update is confirmed. Action: type: object description: >- Describes the next client action required to continue or complete a payment flow. It is typically returned when the status is NEXT_ACTION. properties: redirectUrl: type: string description: >- Redirect URL that the client should open or navigate to for the next payment step. method: type: string description: HTTP method used to perform the next action. enum: - GET - POST type: type: string description: Payment method or action type that triggered this next step. enum: - ALIPAY - CARD - CASHAPP - GCASH - KAKAO - PIX - PROMPTPAY - QRIS - TNG - UPI - WECHAT walletHandleRedirectOrDisplayQrCode: $ref: '#/components/schemas/WalletHandleRedirectOrDisplayQrCode' description: >- Wallet-side display or redirect payload used for QR code rendering, mobile auth links, hosted instructions, or fallback URLs. paymentMethodType: type: string description: Payment method type associated with this action. postData: type: object description: Form or request parameters to submit when `method` is `POST`. additionalProperties: type: string SubscriptionApiData: required: - billing - createTime - customerId - paymentInstrumentId - paymentMethodType - priceId - priceSnapshotId - productId - quantity - recurringInvoiceItem - status - subscriptionId type: object properties: merchantReference: type: string subscriptionId: type: string sessionId: type: string customerId: type: string productId: type: string priceId: type: string priceSnapshotId: type: string createTime: type: integer format: int64 quantity: type: integer format: int32 paymentMethodType: type: string paymentInstrumentId: type: string trialStart: type: integer format: int64 trialEnd: type: integer format: int64 currentPeriodStart: type: integer format: int64 currentPeriodEnd: type: integer format: int64 cancelAt: type: integer format: int64 cancelAtPeriodEnd: type: boolean canceledAt: type: integer format: int64 cancelReason: type: string status: type: string billing: type: string currency: type: string enum: - USD - EUR - JPY - GBP - AUD - CAD - CNY - HKD - SGD - KRW - AED - THB - IDR - PHP - MYR - BRL - INR recurringInvoiceItem: $ref: '#/components/schemas/InvoiceItemVo' upcomingInvoiceItem: $ref: '#/components/schemas/InvoiceItemVo' scheduledPhases: type: array description: >- Remaining scheduled subscription plan changes that have not taken effect yet. items: $ref: '#/components/schemas/ScheduledPhase' elapsedCycles: type: integer description: >- Number of billing period boundaries already crossed. Compare this with scheduledPhases.effectiveCycle to determine when a remaining phase takes effect. format: int32 metadata: type: object additionalProperties: type: string WalletHandleRedirectOrDisplayQrCode: type: object description: Wallet response payload for redirect flows or QR code display flows. properties: imageUrlPng: type: string description: >- PNG QR code image URL. This field may also contain a Base64-encoded image string. imageUrlSvg: type: string description: >- SVG QR code image URL. This field may also contain a Base64-encoded image string. imageDataUrl: type: string description: Base64-encoded QR code image data URL. hostedInstructionsUrl: type: string description: Hosted instruction or guidance URL for H5 redirection flows. mobileAuthUrl: type: string description: Mobile authorization URL or deeplink used by mobile redirect flows. fallbackUrl: type: string description: Fallback HTTPS URL used when app redirection fails. packageName: type: string description: Android package name used by mobile app redirect flows. expiresAt: type: integer format: int64 description: Expiration time in Unix seconds. expiresSecond: type: integer format: int64 description: Optional countdown in seconds until expiration. InvoiceItemVo: type: object properties: invoiceItemId: type: string amount: type: number discountAmount: type: number paymentAmount: type: number couponTerms: type: string promotionCode: type: string currency: type: string enum: - USD - EUR - JPY - GBP - AUD - CAD - CNY - HKD - SGD - KRW - AED - THB - IDR - PHP - MYR - BRL - INR periodStart: type: integer format: int64 periodEnd: type: integer format: int64 proration: type: boolean price: $ref: '#/components/schemas/PriceVo' ScheduledPhase: required: - sequence - effectiveCycle - priceSnapshotId - quantity type: object description: >- A scheduled subscription plan change that takes effect at a future billing period boundary. properties: sequence: minimum: 1 type: integer description: >- Position of this phase in the schedule. Values must be strictly increasing. format: int32 effectiveCycle: minimum: 1 type: integer description: >- The renewal boundary when this phase takes effect, counted from subscription creation. Values must be strictly increasing. format: int32 priceSnapshotId: type: string description: >- Target subscription price snapshot ID. The snapshot must exist, have priceType=SUBSCRIBE with valid recurring details, and support the subscription payment currency. quantity: minimum: 1 type: integer description: Target quantity for the scheduled phase. format: int32 metadata: type: object description: >- Optional metadata for this scheduled phase. Maximum 20 keys. Key length must be 40 characters or fewer and string value length must be 500 characters or fewer. maxProperties: 20 propertyNames: maxLength: 40 additionalProperties: type: string maxLength: 500 PriceVo: type: object properties: productId: type: string productName: type: string priceId: type: string priceSnapshotId: type: string unitAmount: type: number quantity: type: integer format: int32 recurring: $ref: '#/components/schemas/Recurring' Recurring: required: - interval - pricingModel - tiersMode type: object properties: interval: type: string enum: - week - month - year - day - quarter - half_year - custom description: >- Frequency of recurring charges. `quarter` bills every 3 months, `half_year` bills every 6 months, and `custom` uses interval count to define the cycle. trialPeriodDays: type: integer description: Number of days in the trial period format: int32 pricingModel: type: string enum: - flat_rate - per_seat description: >- Billing model (flat_rate, per_seat, with tiered and usage_based models coming soon) tiersMode: type: string enum: - volume - graduated description: >- Coming soon. Tiered pricing mode, can be volume (quantity-based) or graduated (incremental tiers) intervalCount: type: integer description: >- Number of interval units per billing cycle. For custom intervals, this value represents the number of days. format: int32 description: Recurring billing configuration information securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: >- Your secret API key obtained from the Clink dashboard (Developers section) ````