> ## Documentation Index > Fetch the complete documentation index at: https://waffo.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Subscription change ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/subscription/change openapi: 3.1.0 info: title: acquiring-order description: 接口文档 termsOfService: https://www.waffo.com version: 1.0.0 servers: - url: https://www.waffo.com description: Sandbox API (auto-signed via Next.js proxy) security: [] tags: - name: Order create description: ' Order create api description' - name: Subscription create description: Subscription create api description - name: Subscription inquiry description: Subscription inquiry api description - name: Order inquiry description: Order inquiry api description - name: Subscription cancel description: > Cancel an active subscription when the merchant no longer wishes to continue the recurring billing cycle. This endpoint can only be invoked when the subscription status is active - name: Order cancel description: Order cancel api description - name: Subscription manage description: > This API allows the merchant to request a subscription management URL from Waffo Waffo will generate a subscription management URL which merchant can redirect user to this URL for managing subscription details (e.g. view subscription detail and cancel subscription). This management URL has a fixed expiration time (e.g., 1 day). - name: Order refund description: Order refund api description - name: Subscription change description: > This API allows merchants to upgrade or downgrade a user's subscription plan. The change request will create a new subscription based on the original subscription, applying any remaining amount from the original subscription. 此接口允许商户升级或降级用户的订阅计划。升降级请求将基于原订阅创建新订阅，并将原订阅的剩余金额应用到新订阅中。 - name: Refund inquiry description: Refund inquiry api description - name: Subscription change inquiry description: > This API allows merchants to query the status of a subscription change (upgrade/downgrade) request. 此接口允许商户查询订阅升降级请求的状态。 - name: Merchant config inquiry description: Merchant config inquiry api description - name: Pay Method Config Inquiry description: Pay Method Config Inquiry api description paths: /api/v1/subscription/change: post: tags: - Subscription change summary: Subscription change operationId: changeSubscription requestBody: content: application/json: schema: $ref: '#/components/schemas/SubscriptionChangeRequest' required: true responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/ResponseSubscriptionChangeResponse' components: schemas: SubscriptionChangeRequest: type: object description: Subscription change request properties: subscriptionRequest: type: string description: >- New subscription request id sent from Merchant. It will also be used for idempotent check. x-gen: NANOID maxLength: 32 minLength: 0 merchantSubscriptionId: type: string description: New merchant subscription plan ID assigned to this user maxLength: 64 minLength: 0 originSubscriptionRequest: type: string description: Original subscription request id that needs to be changed example: ORG_SUB_REQ_001 maxLength: 32 minLength: 0 remainingAmount: type: string description: >- Remaining amount from the original subscription to be applied to the new subscription example: 50000 maxLength: 24 minLength: 0 currency: type: string description: Subscription currency, for example USD example: USD maxLength: 12 minLength: 0 userCurrency: type: string description: >- User payment currency. This is needed when merchant order currency is NOT the same as user payment currency maxLength: 12 minLength: 0 requestedAt: type: string format: date-time description: Merchant-side request time x-gen: DATETIME_ISO successRedirectUrl: type: string description: >- The address of the merchant page to redirect to after successful subscription change. If no value is provided, it will stay on the cashier page after successful payment. maxLength: 256 minLength: 0 failedRedirectUrl: type: string description: >- The address of the merchant page to which the payment pre-verification fails, or the redirection after the payment fails. If no value is provided, it will stay on the cashier page after the payment fails maxLength: 256 minLength: 0 notifyUrl: type: string description: >- The callback address to notify the merchant after the subscription change is completed / failed example: https://merchant.com/notify maxLength: 256 minLength: 0 cancelRedirectUrl: type: string description: >- User will be redirected to this page if user choose to cancel and not continue the payment maxLength: 512 minLength: 0 subscriptionManagementUrl: type: string description: >- It refers to the subscription management page for users on the merchant side. maxLength: 256 minLength: 0 extendInfo: type: string description: Reserved. Json format e.g. {"key1":"value1", "key2":"value2"} maxLength: 256 minLength: 0 orderExpiredAt: type: string format: date-time description: >- The order expiry time set by merchant. User is required to input payment data on Waffo cashier page prior to merchant's order expiry time. If not provided, the default is 4 hours productInfoList: type: array description: New subscription product information list items: $ref: '#/components/schemas/SubscriptionChangeRequest.ProductInfo' minItems: 1 merchantInfo: $ref: '#/components/schemas/SubscriptionChangeRequest.MerchantInfo' description: Merchant info userInfo: $ref: '#/components/schemas/SubscriptionChangeRequest.UserInfo' description: User info goodsInfo: $ref: '#/components/schemas/SubscriptionChangeRequest.GoodsInfo' description: Merchant goods information addressInfo: $ref: '#/components/schemas/SubscriptionChangeRequest.AddressInfo' description: Address Information brandInfo: $ref: '#/components/schemas/BrandInfo' description: Brand display information for cashier paymentInfo: $ref: '#/components/schemas/SubscriptionChangeRequest.PaymentInfo' description: Payment information riskData: $ref: '#/components/schemas/SubscriptionChangeRequest.RiskData' description: Risk data for compliance and risk management required: - currency - goodsInfo - merchantInfo - notifyUrl - originSubscriptionRequest - paymentInfo - productInfoList - remainingAmount - requestedAt - subscriptionRequest - userInfo ResponseSubscriptionChangeResponse: type: object description: response data properties: code: type: string msg: type: string data: $ref: '#/components/schemas/SubscriptionChangeResponse' SubscriptionChangeRequest.ProductInfo: type: object description: Subscription product information properties: description: type: string description: >- Subscription product description, often appearing to user when asking user's confirmation example: Premium Monthly Subscription maxLength: 128 minLength: 0 periodType: type: string description: 'Subscription product period type: - DAILY - WEEKLY - MONTHLY' example: MONTHLY maxLength: 12 minLength: 0 amount: type: string description: Subscription amount for this product example: 100000 maxLength: 12 minLength: 0 periodInterval: type: string description: >- Period interval. If the period type is WEEKLY, the period interval is between 1-4. If the period type is MONTHLY, the period interval is between 1-12. For example if the period type is weekly, the period interval is 2, it means every 2 weeks time user will pay for the subscription amount example: 1 maxLength: 12 minLength: 0 numberOfPeriod: type: string description: >- Specify after how many deduction period, the subscription will end. The value needs to be greater than 1. For example 3. If the value is empty, it means the subscription has no defined end period. Note: The Dana subscription period shall not exceed three years in total. example: 12 maxLength: 24 minLength: 0 trialPeriodAmount: type: string description: >- The subscription amount that user pay during the trial period, for example 8000. The amount shall >= 0. If the value is empty, there is no trial period example: 0 maxLength: 24 minLength: 0 numberOfTrialPeriod: type: string description: Specify after how many periods, the trial will end. For example 1894 example: 1 maxLength: 12 minLength: 0 trialPeriodType: type: string description: >- Subscription product period type: - DAILY - WEEKLY - MONTHLY. This field is optional when a trial period is configured. If omitted, the system will use periodType value by default. example: MONTHLY maxLength: 12 minLength: 0 trialPeriodInterval: type: string description: >- Represents the interval unit of the trial period. Same definition and behavior as periodInterval. If the period type is DAILY, the period interval is between 1-365. This field is optional when a trial period is configured. If omitted, the system will use periodInterval value by default. example: 1 maxLength: 12 minLength: 0 required: - amount - description - periodInterval - periodType SubscriptionChangeRequest.MerchantInfo: type: object description: Merchant information properties: merchantId: type: string description: Merchant id assigned by Waffo example: M0001 maxLength: 64 minLength: 0 subMerchantId: type: string description: Sub merchant id assigned by Waffo maxLength: 64 minLength: 0 required: - merchantId SubscriptionChangeRequest.UserInfo: type: object description: User information properties: userId: type: string description: Merchant User id example: USER001 maxLength: 64 minLength: 0 userEmail: type: string description: Merchant user email example: user@example.com maxLength: 64 minLength: 0 userTerminal: type: string description: | Merchant user terminal type: - WEB (user is using a PC) - APP (user is using a Mobile Phone) maxLength: 32 minLength: 0 userPhone: type: string description: >- Merchant user mobile phone number: +Country code-Mobile Number, for example +62-08990013157 example: +62-08990013157 maxLength: 16 minLength: 0 userFirstName: type: string description: Merchant user's first name maxLength: 64 minLength: 0 userLastName: type: string description: Merchant user's last name maxLength: 64 minLength: 0 userCreatedAt: type: string format: date-time description: Merchant user creation time required: - userEmail - userId SubscriptionChangeRequest.GoodsInfo: type: object description: Goods information properties: goodsId: type: string description: Goods item id example: GOODS001 maxLength: 32 minLength: 0 goodsName: type: string description: Goods item name example: Premium Subscription Plan maxLength: 64 minLength: 0 goodsCategory: type: string description: Goods category maxLength: 32 minLength: 0 goodsUrl: type: string description: >- Goods URL from merchant website, for example https://www.merchant123.com/goods123 (for compliance and risk management purpose) maxLength: 128 minLength: 0 appName: type: string description: >- App package name, for example com.example.app123 (for compliance and risk management purpose) maxLength: 32 minLength: 0 skuName: type: string description: Goods sku name maxLength: 32 minLength: 0 goodsUniquePrice: type: string description: Goods price maxLength: 16 minLength: 0 goodsQuantity: type: integer format: int32 description: Goods quantity required: - goodsId - goodsName SubscriptionChangeRequest.AddressInfo: type: object description: Address information properties: address: type: string description: Shipping address maxLength: 256 minLength: 0 city: type: string description: Shipping city maxLength: 32 minLength: 0 region: type: string description: Shipping region / state / province maxLength: 32 minLength: 0 postcode: type: string description: Shipping postcode maxLength: 16 minLength: 0 addressCountryCode: type: string description: Shipping country code maxLength: 16 minLength: 0 BrandInfo: type: object description: Brand display information for cashier properties: cashierLogoUrl: type: string description: |2 Merchant logo for cashier display. - It supports external URL from merchant, and the format starts with https://, and the recommended size is 40x40 px - It also supports the pre-created logo ID via https://dashboard.waffo.com/checkout/cashier-customization and the format starts with logo_ maxLength: 512 minLength: 0 cashierDisplayName: type: string description: Merchant display name for cashier maxLength: 128 minLength: 0 cashierProductImageUrl: type: string description: >- Product image URL for cashier display. Starts with https://. Recommended size: 1200x630 px maxLength: 512 minLength: 0 SubscriptionChangeRequest.PaymentInfo: type: object description: Payment information properties: productName: type: string description: > Payment product: - SUBSCRIPTION Merchant can view the signed contract product via Waffo Merchant portal example: SUBSCRIPTION maxLength: 32 minLength: 0 payMethodType: type: string description: > Payment method type. e.g. - EWALLET - CREDITCARD - DEBITCARD Merchant can provide a list of pay methods type as the filtering logic. If not provided, Waffo will choose all eligible payment methods based on merchant contract Conditional (must be provided for card payments) maxLength: 256 minLength: 0 payMethodName: type: string description: > The actual payment method. e.g. DANA If payMethodName is provided, the payment request will be processed using this pay method directly Conditional (required for non-card payment methods) maxLength: 24 minLength: 0 payMethodProperties: type: string description: >- For certain pay methods, there could be certain specific info needed. Json format e.g. {"key1":"value1", "key2":"value2"} maxLength: 256 minLength: 0 payMethodUserAccountType: type: string description: >- User account type at the designated pay method: EMAIL, PHONE_NO, ACCOUNT_ID maxLength: 24 minLength: 0 payMethodUserAccountNo: type: string description: User account number at the designated pay method maxLength: 64 minLength: 0 payMethodUserAccessToken: type: string description: >- User access token is required when using MINI_PROGRAM_SUBSCRIPTION product. The user access token can be obtained from mini program API maxLength: 128 minLength: 0 cashierAppearance: type: string description: >- Defines the overall appearance configuration of the UI, including colors, background, and typography settings. A JSON-formatted string containing theme variables. required: - productName SubscriptionChangeRequest.RiskData: type: object description: Risk data for compliance and risk management properties: userType: type: string description: 'Merchant user: Individual / Agent / Institution / Internal' maxLength: 24 minLength: 0 userCategory: type: string description: 'Merchant user: Member / Non-Member' maxLength: 24 minLength: 0 userLegalName: type: string description: Merchant user legal name (or first name + last name) maxLength: 128 minLength: 0 userDisplayName: type: string description: Merchant user display name maxLength: 128 minLength: 0 userRegistrationIp: type: string description: Merchant user registration IP address maxLength: 24 minLength: 0 userLastSeenIp: type: string description: Merchant user last login IP address maxLength: 24 minLength: 0 userIsNew: type: string description: 'Merchant user if he/she is a new user: Yes / No' maxLength: 8 minLength: 0 userIsFirstPurchase: type: string description: 'Merchant user if this is his/her first purchase: Yes / No' maxLength: 8 minLength: 0 SubscriptionChangeResponse: type: object description: Subscription change response properties: originSubscriptionRequest: type: string description: Original subscription request id that was changed subscriptionRequest: type: string description: New subscription request id after the change merchantSubscriptionId: type: string description: Merchant's new subscription plan ID assigned to this user subscriptionChangeStatus: type: string description: >- Subscription change status: - IN_PROGRESS (payment request initiated) - AUTHORIZATION_REQUIRED (user needs to authorize payment) - SUCCESS (subscription change completed) - CLOSED (subscription change failed or timeout) subscriptionAction: type: string description: >- When subscriptionChangeStatus = AUTHORIZATION_REQUIRED, merchant follow the following: "webUrl": redirect user to this URL subscriptionId: type: string description: New Waffo subscription Id required: - subscriptionId ````