> ## Documentation Index > Fetch the complete documentation index at: https://docs.unibee.dev/llms.txt > Use this file to discover all available pages before exploring further. # Update Subscription ## Endpoint Overview **POST** `https://api.unibee.dev/merchant/subscription/update_submit` Update Subscription *** ## Authorization All UniBee Merchant API requests require authentication via API key. | Header | Required | Description | | --------------- | -------- | ------------------------------------- | | `Authorization` | Yes | Bearer `` | | `Content-Type` | Yes | `application/json` (for request body) | *** ## Parameters Parameters for this endpoint are listed below. The schema is also shown in the Try it panel. ### Request body | Name | Type | Required | Description | | ------------------------ | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `addonParams` | array | No | Optional. Target addon configuration after the update. | | `applyPromoCredit` | boolean | No | Optional. Whether to apply available promo credit when creating the update invoice. | | `applyPromoCreditAmount` | integer | No | Optional. Maximum promo credit amount to apply. If omitted and applyPromoCredit is true, the system auto-computes the usable amount. | | `cancelUrl` | string | No | Optional. URL to redirect the customer to when the customer cancels or the update payment fails. | | `confirmCurrency` | string | No | Optional. When provided, represents the expected currency code for the update invoice and must match the value returned from update\_preview, otherwise the request is rejected. | | `confirmTotalAmount` | integer | No | Optional. When provided, represents the expected total amount (in minor units) for the update invoice and must match the value returned from update\_preview, otherwise the request is rejected. | | `currency` | string | No | Optional. Target currency for the updated subscription. If not provided, use current subscription currency. Currency change is not allowed when a proration invoice is required. | | `discount` | string | No | | | `discountCode` | string | No | Optional. Discount or coupon code applied to this update. Overrides the subscription's recurring discount for this invoice. | | `effectImmediate` | integer | No | Optional. Override for when to apply the plan change: 1 = immediate (current period, proration will be computed if needed), 2 = at next period (no proration in current period). If 0 or omitted, the system uses default rules (immediate for upgrades, merchant configuration for downgrades, and immediate for non-active subscriptions). | | `gatewayId` | integer | No | Optional. Gateway ID to be used for the invoice generated by this update. If omitted, the subscription's current gateway is used. | | `gatewayPaymentType` | string | No | Optional. Payment type for the selected gateway, such as card, wallet, etc. | | `manualPayment` | boolean | No | Optional. If true, do not create an automatic payment for the update invoice; the invoice will be created in open status for manual collection. | | `metadata` | object | No | Optional. Custom metadata map that will be stored on the update invoice and subscription pending update record. | | `newPlanId` | integer | Yes | Required. Target plan ID to switch the subscription to. | | `paymentUIMode` | string | No | Optional. Checkout UI mode: hosted \| embedded \| custom. Default is hosted. | | `productData` | string | No | | | `prorationDate` | integer | No | Optional. UTC timestamp at which proration should start when effectImmediate = 1. Defaults to current time if not provided. | | `quantity` | integer | Yes | Required. Target quantity for the subscription after update. | | `returnUrl` | string | No | Optional. URL to redirect the customer to after the update is completed or payment succeeds. | | `subscriptionId` | string | No | Optional. SubscriptionId to be upgraded or downgraded. Either subscriptionId or userId must be provided. When userId is used instead of subscriptionId, the only active subscription of that user will be updated. | | `taxPercentage` | integer | No | Optional. External tax percentage override for the update invoice, in basis points (e.g. 1000 = 10%%). Overrides the subscription taxPercentage when provided. | | `userId` | integer | No | Optional. UserId associated with the subscription to update. Either subscriptionId or userId must be provided. When subscriptionId is omitted, the system uses this userId to locate the active subscription. | *** ## Request examples ### cURL ```bash theme={null} curl -X POST "https://api.unibee.dev/merchant/subscription/update_submit" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "addonParams": [], "applyPromoCredit": false, "applyPromoCreditAmount": 0, "cancelUrl": "https://example.com", "confirmCurrency": "", "confirmTotalAmount": 0, "currency": "", "discount": "", "discountCode": "", "effectImmediate": 0, "gatewayId": 0, "gatewayPaymentType": "", "manualPayment": false, "metadata": {}, "newPlanId": 0, "paymentUIMode": "", "productData": "", "prorationDate": 0, "quantity": 0, "returnUrl": "https://example.com", "subscriptionId": "id_example", "taxPercentage": 0, "userId": 0 }' ``` ### Sandbox ```bash theme={null} curl -X POST "https://api-sandbox.unibee.top/merchant/subscription/update_submit" \ -H "Authorization: Bearer YOUR_SANDBOX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "addonParams": [], "applyPromoCredit": false, "applyPromoCreditAmount": 0, "cancelUrl": "https://example.com", "confirmCurrency": "", "confirmTotalAmount": 0, "currency": "", "discount": "", "discountCode": "", "effectImmediate": 0, "gatewayId": 0, "gatewayPaymentType": "", "manualPayment": false, "metadata": {}, "newPlanId": 0, "paymentUIMode": "", "productData": "", "prorationDate": 0, "quantity": 0, "returnUrl": "https://example.com", "subscriptionId": "id_example", "taxPercentage": 0, "userId": 0 }' ``` *** ## Response Success responses return a JSON envelope with `code`, `data`, `message`, `redirect`, and `requestId`. `code` `0` indicates success. | Field | Type | Description | | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | | `code` | integer | Response code. `0` = success | | `data` | object | Response payload | | `data.action` | object | | | `data.invoiceId` | string | ID of the invoice generated by this update (proration or next-period invoice, depending on effectImmediate). | | `data.link` | string | Hosted payment or invoice link. When paid=false and an invoice exists, redirect the customer to this link to complete payment. | | `data.note` | string | Additional message describing the update result, used for internal or merchant-facing explanations. | | `data.paid` | boolean | Whether the update invoice has been successfully paid at the time of response. | | `data.paymentId` | string | ID of the payment created for the update invoice, if any. | | `data.subscriptionPendingUpdate` | object | | | `message` | string | Human-readable message | | `requestId` | string | Request ID for support | *** ## Error handling | HTTP status | Meaning | | ----------- | ------------------------------------------------------------------------- | | 400 | Bad request — invalid or missing parameters. Check `message` in the body. | | 401 | Unauthorized — missing or invalid API key. | | 404 | Not found — invalid path or resource. | | 500 | Server error — retry with backoff. | When `code` in the response body is non-zero, check `message` for details. Use `requestId` when contacting support. ## OpenAPI ````yaml post /merchant/subscription/update_submit openapi: 3.0.0 info: description: UniBee Api Server license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html title: OpenAPI UniBee version: daily,buildtime:202603161017 servers: - url: https://api.unibee.dev - url: https://api-sandbox.unibee.top security: - Authorization: [] paths: /merchant/subscription/update_submit: post: tags: - Subscription Update summary: Update Subscription requestBody: content: application/json: schema: $ref: '#/components/schemas/unibee.api.merchant.subscription.UpdateReq' required: true responses: '200': content: application/json: schema: properties: code: format: int properties: {} type: integer data: properties: action: $ref: >- #/components/schemas/github.com.gogf.gf.v2.encoding.gjson.Json invoiceId: description: >- ID of the invoice generated by this update (proration or next-period invoice, depending on effectImmediate). format: string properties: {} type: string link: description: >- Hosted payment or invoice link. When paid=false and an invoice exists, redirect the customer to this link to complete payment. format: string properties: {} type: string note: description: >- Additional message describing the update result, used for internal or merchant-facing explanations. format: string properties: {} type: string paid: description: >- Whether the update invoice has been successfully paid at the time of response. format: bool properties: {} type: boolean paymentId: description: >- ID of the payment created for the update invoice, if any. format: string properties: {} type: string subscriptionPendingUpdate: $ref: >- #/components/schemas/unibee.api.bean.detail.SubscriptionPendingUpdateDetail type: object merchantId: format: int64 properties: {} type: integer message: format: string properties: {} type: string redirect: format: string properties: {} type: string requestId: format: string properties: {} type: string type: object description: '' components: schemas: unibee.api.merchant.subscription.UpdateReq: properties: addonParams: description: Optional. Target addon configuration after the update. format: '[]*bean.PlanAddonParam' items: $ref: '#/components/schemas/unibee.api.bean.PlanAddonParam' properties: {} type: array applyPromoCredit: description: >- Optional. Whether to apply available promo credit when creating the update invoice. format: bool properties: {} type: boolean applyPromoCreditAmount: description: >- Optional. Maximum promo credit amount to apply. If omitted and applyPromoCredit is true, the system auto-computes the usable amount. format: '*int64' properties: {} type: integer cancelUrl: description: >- Optional. URL to redirect the customer to when the customer cancels or the update payment fails. format: string properties: {} type: string confirmCurrency: description: >- Optional. When provided, represents the expected currency code for the update invoice and must match the value returned from update_preview, otherwise the request is rejected. format: string properties: {} type: string confirmTotalAmount: description: >- Optional. When provided, represents the expected total amount (in minor units) for the update invoice and must match the value returned from update_preview, otherwise the request is rejected. format: int64 properties: {} type: integer currency: description: >- Optional. Target currency for the updated subscription. If not provided, use current subscription currency. Currency change is not allowed when a proration invoice is required. format: '*string' properties: {} type: string discount: $ref: '#/components/schemas/unibee.api.bean.ExternalDiscountParam' discountCode: description: >- Optional. Discount or coupon code applied to this update. Overrides the subscription's recurring discount for this invoice. format: string properties: {} type: string effectImmediate: description: >- Optional. Override for when to apply the plan change: 1 = immediate (current period, proration will be computed if needed), 2 = at next period (no proration in current period). If 0 or omitted, the system uses default rules (immediate for upgrades, merchant configuration for downgrades, and immediate for non-active subscriptions). format: int properties: {} type: integer gatewayId: description: >- Optional. Gateway ID to be used for the invoice generated by this update. If omitted, the subscription's current gateway is used. format: '*int64' properties: {} type: integer gatewayPaymentType: description: >- Optional. Payment type for the selected gateway, such as card, wallet, etc. format: string properties: {} type: string manualPayment: description: >- Optional. If true, do not create an automatic payment for the update invoice; the invoice will be created in open status for manual collection. format: bool properties: {} type: boolean metadata: additionalProperties: $ref: '#/components/schemas/interface' description: >- Optional. Custom metadata map that will be stored on the update invoice and subscription pending update record. format: map[string]interface {} properties: {} type: object newPlanId: description: Required. Target plan ID to switch the subscription to. format: int64 properties: {} type: integer paymentUIMode: description: >- Optional. Checkout UI mode: hosted | embedded | custom. Default is hosted. format: string properties: {} type: string productData: $ref: '#/components/schemas/unibee.api.bean.PlanProductParam' prorationDate: description: >- Optional. UTC timestamp at which proration should start when effectImmediate = 1. Defaults to current time if not provided. format: '*int64' properties: {} type: integer quantity: description: Required. Target quantity for the subscription after update. format: int64 properties: {} type: integer returnUrl: description: >- Optional. URL to redirect the customer to after the update is completed or payment succeeds. format: string properties: {} type: string subscriptionId: description: >- Optional. SubscriptionId to be upgraded or downgraded. Either subscriptionId or userId must be provided. When userId is used instead of subscriptionId, the only active subscription of that user will be updated. format: string properties: {} type: string taxPercentage: description: >- Optional. External tax percentage override for the update invoice, in basis points (e.g. 1000 = 10%%). Overrides the subscription taxPercentage when provided. format: '*int64' properties: {} type: integer userId: description: >- Optional. UserId associated with the subscription to update. Either subscriptionId or userId must be provided. When subscriptionId is omitted, the system uses this userId to locate the active subscription. format: int64 properties: {} type: integer required: - newPlanId - quantity type: object github.com.gogf.gf.v2.encoding.gjson.Json: properties: {} type: object unibee.api.bean.detail.SubscriptionPendingUpdateDetail: properties: addonData: description: plan addon json data format: string properties: {} type: string addons: description: Addons format: '[]*bean.PlanAddonDetail' items: $ref: '#/components/schemas/unibee.api.bean.PlanAddonDetail' properties: {} type: array amount: description: CaptureAmount, Cent format: int64 properties: {} type: integer currency: description: Currency format: string properties: {} type: string effectImmediate: description: EffectImmediate format: int properties: {} type: integer effectTime: description: effect_immediate=0, EffectTime unit_time format: int64 properties: {} type: integer gatewayId: description: Id format: int64 properties: {} type: integer gmtCreate: description: GmtCreate format: '*gtime.Time' properties: {} type: string gmtModify: description: GmtModify format: '*gtime.Time' properties: {} type: string invoiceId: description: invoice id format: string properties: {} type: string link: description: Link format: string properties: {} type: string merchantId: description: MerchantId format: int64 properties: {} type: integer merchantMember: $ref: '#/components/schemas/unibee.api.bean.detail.MerchantMemberDetail' metadata: additionalProperties: $ref: '#/components/schemas/interface' format: map[string]interface {} properties: {} type: object note: description: Update Note format: string properties: {} type: string paid: description: Paid format: int properties: {} type: integer pendingUpdateId: description: PendingUpdateId format: string properties: {} type: string plan: $ref: '#/components/schemas/unibee.api.bean.Plan' planId: description: PlanId format: int64 properties: {} type: integer prorationAmount: description: ProrationAmount,Cents format: int64 properties: {} type: integer quantity: description: quantity format: int64 properties: {} type: integer status: description: Status，1-Pending｜2-Finished｜3-Cancelled format: int properties: {} type: integer subscriptionId: description: SubscriptionId format: string properties: {} type: string updateAddonData: description: UpdateAddonData format: string properties: {} type: string updateAddons: description: UpdateAddons format: '[]*bean.PlanAddonDetail' items: $ref: '#/components/schemas/unibee.api.bean.PlanAddonDetail' properties: {} type: array updateAmount: description: UpdateAmount, Cents format: int64 properties: {} type: integer updateCurrency: description: UpdateCurrency format: string properties: {} type: string updatePlan: $ref: '#/components/schemas/unibee.api.bean.Plan' updatePlanId: description: UpdatePlanId format: int64 properties: {} type: integer updateQuantity: description: UpdateQuantity format: int64 properties: {} type: integer userId: description: UserId format: int64 properties: {} type: integer type: object unibee.api.bean.PlanAddonParam: properties: addonPlanId: description: AddonPlanId format: int64 properties: {} type: integer quantity: description: Quantity，Default 1 format: int64 properties: {} type: integer type: object unibee.api.bean.ExternalDiscountParam: properties: cycleLimit: description: >- the count limitation of subscription recurring cycle, recurring need enable if cycleLimit set format: '*int' properties: {} type: integer discountAmount: description: Amount of discount format: '*int64' properties: {} type: integer discountPercentage: description: Percentage of discount, 100=1%, ignore if discountAmount set format: '*int64' properties: {} type: integer endTime: description: end of discount available utc time format: '*int64' properties: {} type: integer metadata: additionalProperties: $ref: '#/components/schemas/interface' description: Metadata，Map format: map[string]interface {} properties: {} type: object recurring: description: Discount recurring enable, default false format: '*bool' properties: {} type: boolean type: object interface: properties: {} type: object unibee.api.bean.PlanProductParam: properties: description: description: Description format: string properties: {} type: string name: description: Name format: string properties: {} type: string type: object unibee.api.bean.PlanAddonDetail: properties: addonPlan: $ref: '#/components/schemas/unibee.api.bean.Plan' quantity: description: Quantity format: int64 properties: {} type: integer type: object unibee.api.bean.detail.MerchantMemberDetail: properties: MemberGroupPermission: additionalProperties: $ref: '#/components/schemas/unibee.api.bean.MerchantRolePermission' description: The member group permission map' format: map[string]*bean.MerchantRolePermission properties: {} type: object MemberRoles: description: The member role list' format: '[]*bean.MerchantRole' items: $ref: '#/components/schemas/unibee.api.bean.MerchantRole' properties: {} type: array createTime: description: create utc time format: int64 properties: {} type: integer currentDeviceIdentity: description: The Current DeviceIdentity' format: string properties: {} type: string deviceList: description: The devices list' format: '[]*bean.MerchantMemberDevice' items: $ref: '#/components/schemas/unibee.api.bean.MerchantMemberDevice' properties: {} type: array email: description: email format: string properties: {} type: string firstName: description: first name format: string properties: {} type: string id: description: userId format: int64 properties: {} type: integer isBlankPasswd: description: is blank password format: bool properties: {} type: boolean isOwner: description: Check Member is Owner format: bool properties: {} type: boolean lastName: description: last name format: string properties: {} type: string merchantId: description: merchant id format: int64 properties: {} type: integer mobile: description: mobile format: string properties: {} type: string oauthAccounts: description: List of connected OAuth accounts format: '[]*bean.Oauth' items: $ref: '#/components/schemas/unibee.api.bean.Oauth' properties: {} type: array status: description: 0-Active, 2-Suspend format: int properties: {} type: integer totpType: description: >- 0-Inactive, 1-General, Google Authenticator | 2-Microsoft Authenticator | 3-Authy | 4-1Password | 5-LastPass | 6-FreeOTP | 7-Other TOTP format: int properties: {} type: integer type: object unibee.api.bean.Plan: properties: amount: description: amount, cent, without tax format: int64 properties: {} type: integer bindingAddonIds: description: binded recurring addon planIds，split with , format: string properties: {} type: string bindingOnetimeAddonIds: description: binded onetime addon planIds，split with , format: string properties: {} type: string cancelAtTrialEnd: description: >- whether cancel at subscription first trial end，0-false | 1-true, will pass to cancelAtPeriodEnd of subscription format: int properties: {} type: integer checkoutUrl: description: CheckoutUrl format: string properties: {} type: string createTime: description: create utc time format: int64 properties: {} type: integer currency: description: currency format: string properties: {} type: string description: description: description format: string properties: {} type: string disableAutoCharge: description: disable auto-charge, 0-false,1-true format: int properties: {} type: integer externalPlanId: description: external_user_id format: string properties: {} type: string extraMetricData: format: string properties: {} type: string gasPayer: description: who pay the gas, merchant|user format: string properties: {} type: string homeUrl: description: home_url format: string properties: {} type: string id: format: int64 properties: {} type: integer imageUrl: description: image_url format: string properties: {} type: string internalName: description: PlanInternalName format: string properties: {} type: string intervalCount: description: period unit count format: int properties: {} type: integer intervalUnit: description: period unit,day|month|year|week format: string properties: {} type: string merchantId: description: merchant id format: int64 properties: {} type: integer metadata: additionalProperties: $ref: '#/components/schemas/interface' format: map[string]interface {} properties: {} type: object metricLimits: description: Plan's MetricLimit List format: '[]*bean.PlanMetricLimitParam' items: $ref: '#/components/schemas/unibee.api.bean.PlanMetricLimitParam' properties: {} type: array metricMeteredCharge: description: Plan's MetricMeteredCharge format: '[]*bean.PlanMetricMeteredChargeParam' items: $ref: '#/components/schemas/unibee.api.bean.PlanMetricMeteredChargeParam' properties: {} type: array metricRecurringCharge: description: Plan's MetricRecurringCharge format: '[]*bean.PlanMetricMeteredChargeParam' items: $ref: '#/components/schemas/unibee.api.bean.PlanMetricMeteredChargeParam' properties: {} type: array multiCurrencies: description: Plan's MultiCurrencies format: '[]*bean.PlanMultiCurrency' items: $ref: '#/components/schemas/unibee.api.bean.PlanMultiCurrency' properties: {} type: array planName: description: PlanName format: string properties: {} type: string productId: description: product id format: int64 properties: {} type: integer publishStatus: description: 1-UnPublish,2-Publish, Use For Display Plan At UserPortal format: int properties: {} type: integer status: description: status，1-editing，2-active，3-inactive，4-soft archive, 5-hard archive format: int properties: {} type: integer taxPercentage: description: TaxPercentage 1000 = 10% format: int properties: {} type: integer trialAmount: description: price of trial period format: int64 properties: {} type: integer trialDemand: format: string properties: {} type: string trialDurationTime: description: duration of trial format: int64 properties: {} type: integer type: description: type，1-main plan，2-addon plan format: int properties: {} type: integer usVATConfig: $ref: '#/components/schemas/unibee.api.bean.USVATConfig' type: object unibee.api.bean.MerchantRolePermission: properties: group: description: Group format: string properties: {} type: string permissions: description: Permissions format: '[]string' items: format: string properties: {} type: string properties: {} type: array type: object unibee.api.bean.MerchantRole: properties: createTime: description: create utc time format: int64 properties: {} type: integer id: description: id format: int64 properties: {} type: integer merchantId: description: merchant id format: int64 properties: {} type: integer permissions: description: permissions format: '[]*bean.MerchantRolePermission' items: $ref: '#/components/schemas/unibee.api.bean.MerchantRolePermission' properties: {} type: array role: description: role format: string properties: {} type: string type: object unibee.api.bean.MerchantMemberDevice: properties: currentDevice: description: Is CurrentDevice format: bool properties: {} type: boolean identity: description: Identity format: string properties: {} type: string ipAddress: description: IP Address format: string properties: {} type: string lastActiveTime: description: Last Active Time format: int64 properties: {} type: integer lastLoginTime: description: Last Login Time format: int64 properties: {} type: integer lastTotpVerificationTime: description: Last Totp Verification Time format: int64 properties: {} type: integer name: description: Name format: string properties: {} type: string status: description: true-Active, false-Offline format: bool properties: {} type: boolean type: object unibee.api.bean.Oauth: properties: email: format: string properties: {} type: string emailVerified: format: bool properties: {} type: boolean image: format: string properties: {} type: string name: format: string properties: {} type: string provider: format: string properties: {} type: string providerId: format: string properties: {} type: string type: object unibee.api.bean.PlanMetricLimitParam: properties: metricId: description: MetricId format: int64 properties: {} type: integer metricLimit: description: MetricLimit format: int64 properties: {} type: integer type: object unibee.api.bean.PlanMetricMeteredChargeParam: properties: chargeType: description: ChargeType,0-standard pricing 1-graduated pricing format: int properties: {} type: integer graduatedAmounts: description: GraduatedAmounts, used for graduated pricing format: '[]*bean.MetricPlanChargeGraduatedStep' items: $ref: '#/components/schemas/unibee.api.bean.MetricPlanChargeGraduatedStep' properties: {} type: array metricId: description: MetricId format: int64 properties: {} type: integer standardAmount: description: StandardAmount, cent, used for standard pricing,cent format: int64 properties: {} type: integer standardStartValue: description: StandardStartValue, used for standard pricing format: int64 properties: {} type: integer type: object unibee.api.bean.PlanMultiCurrency: properties: amount: description: the amount of exchange rate format: int64 properties: {} type: integer autoExchange: description: >- using https://app.exchangerate-api.com/ to update exchange rate if true, the exchange APIKey need setup first format: bool properties: {} type: boolean currency: description: target currency format: string properties: {} type: string disable: description: disable currency exchange format: bool properties: {} type: boolean exchangeRate: description: exchange rate, no setup required if AutoExchange is true format: float64 properties: {} type: number type: object unibee.api.bean.USVATConfig: properties: active: format: bool properties: {} type: boolean fromAddress: $ref: '#/components/schemas/unibee.api.bean.USAddress' nexusAddresses: format: '[]*bean.USAddress' items: $ref: '#/components/schemas/unibee.api.bean.USAddress' properties: {} type: array sellOnUSOnly: format: bool properties: {} type: boolean taxCode: format: string properties: {} type: string toAddress: $ref: '#/components/schemas/unibee.api.bean.USAddress' type: object unibee.api.bean.MetricPlanChargeGraduatedStep: properties: endValue: description: EndValue, -1 = infinity value(∞) format: int64 properties: {} type: integer flatAmount: description: FlatAmount,cent format: int64 properties: {} type: integer perAmount: description: PerAmount,cent format: int64 properties: {} type: integer startValue: description: StartValue format: int64 properties: {} type: integer type: object unibee.api.bean.USAddress: properties: address: format: string properties: {} type: string city: format: string properties: {} type: string countryCode: format: string properties: {} type: string state: format: string properties: {} type: string verified: format: bool properties: {} type: boolean zipCode: format: string properties: {} type: string type: object securitySchemes: Authorization: bearerFormat: JWT scheme: bearer type: http ````