Skip to main content
POST
/
merchant
/
subscription
/
update_submit
Update Subscription
curl --request POST \
  --url https://api.unibee.dev/merchant/subscription/update_submit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "newPlanId": 123,
  "quantity": 123,
  "addonParams": [
    {
      "addonPlanId": 123,
      "quantity": 123
    }
  ],
  "applyPromoCredit": true,
  "applyPromoCreditAmount": 123,
  "cancelUrl": "<string>",
  "confirmCurrency": "<string>",
  "confirmTotalAmount": 123,
  "currency": "<string>",
  "discount": {
    "cycleLimit": 123,
    "discountAmount": 123,
    "discountPercentage": 123,
    "endTime": 123,
    "metadata": {},
    "recurring": true
  },
  "discountCode": "<string>",
  "effectImmediate": 123,
  "gatewayId": 123,
  "gatewayPaymentType": "<string>",
  "manualPayment": true,
  "metadata": {},
  "paymentUIMode": "<string>",
  "productData": {
    "description": "<string>",
    "name": "<string>"
  },
  "prorationDate": 123,
  "returnUrl": "<string>",
  "subscriptionId": "<string>",
  "taxPercentage": 123,
  "userId": 123
}
'
{
  "code": 123,
  "data": {
    "action": {},
    "invoiceId": "<string>",
    "link": "<string>",
    "note": "<string>",
    "paid": true,
    "paymentId": "<string>",
    "subscriptionPendingUpdate": {
      "addonData": "<string>",
      "addons": [
        {
          "addonPlan": {
            "amount": 123,
            "bindingAddonIds": "<string>",
            "bindingOnetimeAddonIds": "<string>",
            "cancelAtTrialEnd": 123,
            "checkoutUrl": "<string>",
            "createTime": 123,
            "currency": "<string>",
            "description": "<string>",
            "disableAutoCharge": 123,
            "externalPlanId": "<string>",
            "extraMetricData": "<string>",
            "gasPayer": "<string>",
            "homeUrl": "<string>",
            "id": 123,
            "imageUrl": "<string>",
            "internalName": "<string>",
            "intervalCount": 123,
            "intervalUnit": "<string>",
            "merchantId": 123,
            "metadata": {},
            "metricLimits": [
              {
                "metricId": 123,
                "metricLimit": 123
              }
            ],
            "metricMeteredCharge": [
              {
                "chargeType": 123,
                "graduatedAmounts": [
                  {
                    "endValue": 123,
                    "flatAmount": 123,
                    "perAmount": 123,
                    "startValue": 123
                  }
                ],
                "metricId": 123,
                "standardAmount": 123,
                "standardStartValue": 123
              }
            ],
            "metricRecurringCharge": [
              {
                "chargeType": 123,
                "graduatedAmounts": [
                  {
                    "endValue": 123,
                    "flatAmount": 123,
                    "perAmount": 123,
                    "startValue": 123
                  }
                ],
                "metricId": 123,
                "standardAmount": 123,
                "standardStartValue": 123
              }
            ],
            "multiCurrencies": [
              {
                "amount": 123,
                "autoExchange": true,
                "currency": "<string>",
                "disable": true,
                "exchangeRate": 123
              }
            ],
            "planName": "<string>",
            "productId": 123,
            "publishStatus": 123,
            "status": 123,
            "taxPercentage": 123,
            "trialAmount": 123,
            "trialDemand": "<string>",
            "trialDurationTime": 123,
            "type": 123,
            "usVATConfig": {
              "active": true,
              "fromAddress": {
                "address": "<string>",
                "city": "<string>",
                "countryCode": "<string>",
                "state": "<string>",
                "verified": true,
                "zipCode": "<string>"
              },
              "nexusAddresses": [
                {
                  "address": "<string>",
                  "city": "<string>",
                  "countryCode": "<string>",
                  "state": "<string>",
                  "verified": true,
                  "zipCode": "<string>"
                }
              ],
              "sellOnUSOnly": true,
              "taxCode": "<string>",
              "toAddress": {
                "address": "<string>",
                "city": "<string>",
                "countryCode": "<string>",
                "state": "<string>",
                "verified": true,
                "zipCode": "<string>"
              }
            }
          },
          "quantity": 123
        }
      ],
      "amount": 123,
      "currency": "<string>",
      "effectImmediate": 123,
      "effectTime": 123,
      "gatewayId": 123,
      "gmtCreate": "<string>",
      "gmtModify": "<string>",
      "invoiceId": "<string>",
      "link": "<string>",
      "merchantId": 123,
      "merchantMember": {
        "MemberGroupPermission": {},
        "MemberRoles": [
          {
            "createTime": 123,
            "id": 123,
            "merchantId": 123,
            "permissions": [
              {
                "group": "<string>",
                "permissions": [
                  "<string>"
                ]
              }
            ],
            "role": "<string>"
          }
        ],
        "createTime": 123,
        "currentDeviceIdentity": "<string>",
        "deviceList": [
          {
            "currentDevice": true,
            "identity": "<string>",
            "ipAddress": "<string>",
            "lastActiveTime": 123,
            "lastLoginTime": 123,
            "lastTotpVerificationTime": 123,
            "name": "<string>",
            "status": true
          }
        ],
        "email": "<string>",
        "firstName": "<string>",
        "id": 123,
        "isBlankPasswd": true,
        "isOwner": true,
        "lastName": "<string>",
        "merchantId": 123,
        "mobile": "<string>",
        "oauthAccounts": [
          {
            "email": "<string>",
            "emailVerified": true,
            "image": "<string>",
            "name": "<string>",
            "provider": "<string>",
            "providerId": "<string>"
          }
        ],
        "status": 123,
        "totpType": 123
      },
      "metadata": {},
      "note": "<string>",
      "paid": 123,
      "pendingUpdateId": "<string>",
      "plan": {
        "amount": 123,
        "bindingAddonIds": "<string>",
        "bindingOnetimeAddonIds": "<string>",
        "cancelAtTrialEnd": 123,
        "checkoutUrl": "<string>",
        "createTime": 123,
        "currency": "<string>",
        "description": "<string>",
        "disableAutoCharge": 123,
        "externalPlanId": "<string>",
        "extraMetricData": "<string>",
        "gasPayer": "<string>",
        "homeUrl": "<string>",
        "id": 123,
        "imageUrl": "<string>",
        "internalName": "<string>",
        "intervalCount": 123,
        "intervalUnit": "<string>",
        "merchantId": 123,
        "metadata": {},
        "metricLimits": [
          {
            "metricId": 123,
            "metricLimit": 123
          }
        ],
        "metricMeteredCharge": [
          {
            "chargeType": 123,
            "graduatedAmounts": [
              {
                "endValue": 123,
                "flatAmount": 123,
                "perAmount": 123,
                "startValue": 123
              }
            ],
            "metricId": 123,
            "standardAmount": 123,
            "standardStartValue": 123
          }
        ],
        "metricRecurringCharge": [
          {
            "chargeType": 123,
            "graduatedAmounts": [
              {
                "endValue": 123,
                "flatAmount": 123,
                "perAmount": 123,
                "startValue": 123
              }
            ],
            "metricId": 123,
            "standardAmount": 123,
            "standardStartValue": 123
          }
        ],
        "multiCurrencies": [
          {
            "amount": 123,
            "autoExchange": true,
            "currency": "<string>",
            "disable": true,
            "exchangeRate": 123
          }
        ],
        "planName": "<string>",
        "productId": 123,
        "publishStatus": 123,
        "status": 123,
        "taxPercentage": 123,
        "trialAmount": 123,
        "trialDemand": "<string>",
        "trialDurationTime": 123,
        "type": 123,
        "usVATConfig": {
          "active": true,
          "fromAddress": {
            "address": "<string>",
            "city": "<string>",
            "countryCode": "<string>",
            "state": "<string>",
            "verified": true,
            "zipCode": "<string>"
          },
          "nexusAddresses": [
            {
              "address": "<string>",
              "city": "<string>",
              "countryCode": "<string>",
              "state": "<string>",
              "verified": true,
              "zipCode": "<string>"
            }
          ],
          "sellOnUSOnly": true,
          "taxCode": "<string>",
          "toAddress": {
            "address": "<string>",
            "city": "<string>",
            "countryCode": "<string>",
            "state": "<string>",
            "verified": true,
            "zipCode": "<string>"
          }
        }
      },
      "planId": 123,
      "prorationAmount": 123,
      "quantity": 123,
      "status": 123,
      "subscriptionId": "<string>",
      "updateAddonData": "<string>",
      "updateAddons": [
        {
          "addonPlan": {
            "amount": 123,
            "bindingAddonIds": "<string>",
            "bindingOnetimeAddonIds": "<string>",
            "cancelAtTrialEnd": 123,
            "checkoutUrl": "<string>",
            "createTime": 123,
            "currency": "<string>",
            "description": "<string>",
            "disableAutoCharge": 123,
            "externalPlanId": "<string>",
            "extraMetricData": "<string>",
            "gasPayer": "<string>",
            "homeUrl": "<string>",
            "id": 123,
            "imageUrl": "<string>",
            "internalName": "<string>",
            "intervalCount": 123,
            "intervalUnit": "<string>",
            "merchantId": 123,
            "metadata": {},
            "metricLimits": [
              {
                "metricId": 123,
                "metricLimit": 123
              }
            ],
            "metricMeteredCharge": [
              {
                "chargeType": 123,
                "graduatedAmounts": [
                  {
                    "endValue": 123,
                    "flatAmount": 123,
                    "perAmount": 123,
                    "startValue": 123
                  }
                ],
                "metricId": 123,
                "standardAmount": 123,
                "standardStartValue": 123
              }
            ],
            "metricRecurringCharge": [
              {
                "chargeType": 123,
                "graduatedAmounts": [
                  {
                    "endValue": 123,
                    "flatAmount": 123,
                    "perAmount": 123,
                    "startValue": 123
                  }
                ],
                "metricId": 123,
                "standardAmount": 123,
                "standardStartValue": 123
              }
            ],
            "multiCurrencies": [
              {
                "amount": 123,
                "autoExchange": true,
                "currency": "<string>",
                "disable": true,
                "exchangeRate": 123
              }
            ],
            "planName": "<string>",
            "productId": 123,
            "publishStatus": 123,
            "status": 123,
            "taxPercentage": 123,
            "trialAmount": 123,
            "trialDemand": "<string>",
            "trialDurationTime": 123,
            "type": 123,
            "usVATConfig": {
              "active": true,
              "fromAddress": {
                "address": "<string>",
                "city": "<string>",
                "countryCode": "<string>",
                "state": "<string>",
                "verified": true,
                "zipCode": "<string>"
              },
              "nexusAddresses": [
                {
                  "address": "<string>",
                  "city": "<string>",
                  "countryCode": "<string>",
                  "state": "<string>",
                  "verified": true,
                  "zipCode": "<string>"
                }
              ],
              "sellOnUSOnly": true,
              "taxCode": "<string>",
              "toAddress": {
                "address": "<string>",
                "city": "<string>",
                "countryCode": "<string>",
                "state": "<string>",
                "verified": true,
                "zipCode": "<string>"
              }
            }
          },
          "quantity": 123
        }
      ],
      "updateAmount": 123,
      "updateCurrency": "<string>",
      "updatePlan": {
        "amount": 123,
        "bindingAddonIds": "<string>",
        "bindingOnetimeAddonIds": "<string>",
        "cancelAtTrialEnd": 123,
        "checkoutUrl": "<string>",
        "createTime": 123,
        "currency": "<string>",
        "description": "<string>",
        "disableAutoCharge": 123,
        "externalPlanId": "<string>",
        "extraMetricData": "<string>",
        "gasPayer": "<string>",
        "homeUrl": "<string>",
        "id": 123,
        "imageUrl": "<string>",
        "internalName": "<string>",
        "intervalCount": 123,
        "intervalUnit": "<string>",
        "merchantId": 123,
        "metadata": {},
        "metricLimits": [
          {
            "metricId": 123,
            "metricLimit": 123
          }
        ],
        "metricMeteredCharge": [
          {
            "chargeType": 123,
            "graduatedAmounts": [
              {
                "endValue": 123,
                "flatAmount": 123,
                "perAmount": 123,
                "startValue": 123
              }
            ],
            "metricId": 123,
            "standardAmount": 123,
            "standardStartValue": 123
          }
        ],
        "metricRecurringCharge": [
          {
            "chargeType": 123,
            "graduatedAmounts": [
              {
                "endValue": 123,
                "flatAmount": 123,
                "perAmount": 123,
                "startValue": 123
              }
            ],
            "metricId": 123,
            "standardAmount": 123,
            "standardStartValue": 123
          }
        ],
        "multiCurrencies": [
          {
            "amount": 123,
            "autoExchange": true,
            "currency": "<string>",
            "disable": true,
            "exchangeRate": 123
          }
        ],
        "planName": "<string>",
        "productId": 123,
        "publishStatus": 123,
        "status": 123,
        "taxPercentage": 123,
        "trialAmount": 123,
        "trialDemand": "<string>",
        "trialDurationTime": 123,
        "type": 123,
        "usVATConfig": {
          "active": true,
          "fromAddress": {
            "address": "<string>",
            "city": "<string>",
            "countryCode": "<string>",
            "state": "<string>",
            "verified": true,
            "zipCode": "<string>"
          },
          "nexusAddresses": [
            {
              "address": "<string>",
              "city": "<string>",
              "countryCode": "<string>",
              "state": "<string>",
              "verified": true,
              "zipCode": "<string>"
            }
          ],
          "sellOnUSOnly": true,
          "taxCode": "<string>",
          "toAddress": {
            "address": "<string>",
            "city": "<string>",
            "countryCode": "<string>",
            "state": "<string>",
            "verified": true,
            "zipCode": "<string>"
          }
        }
      },
      "updatePlanId": 123,
      "updateQuantity": 123,
      "userId": 123
    }
  },
  "merchantId": 123,
  "message": "<string>",
  "redirect": "<string>",
  "requestId": "<string>"
}

​
Endpoint Overview

POST https://api.unibee.dev/merchant/subscription/update_submit Update Subscription

​
Authorization

All UniBee Merchant API requests require authentication via API key.
HeaderRequiredDescription
AuthorizationYesBearer <your_api_key>
Content-TypeYesapplication/json (for request body)

​
Parameters

Parameters for this endpoint are listed below. The schema is also shown in the Try it panel.

​
Request body

NameTypeRequiredDescription
addonParamsarrayNoOptional. Target addon configuration after the update.
applyPromoCreditbooleanNoOptional. Whether to apply available promo credit when creating the update invoice.
applyPromoCreditAmountintegerNoOptional. Maximum promo credit amount to apply. If omitted and applyPromoCredit is true, the system auto-computes the usable amount.
cancelUrlstringNoOptional. URL to redirect the customer to when the customer cancels or the update payment fails.
confirmCurrencystringNoOptional. 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.
confirmTotalAmountintegerNoOptional. 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.
currencystringNoOptional. Target currency for the updated subscription. If not provided, use current subscription currency. Currency change is not allowed when a proration invoice is required.
discountstringNo
discountCodestringNoOptional. Discount or coupon code applied to this update. Overrides the subscription’s recurring discount for this invoice.
effectImmediateintegerNoOptional. 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).
gatewayIdintegerNoOptional. Gateway ID to be used for the invoice generated by this update. If omitted, the subscription’s current gateway is used.
gatewayPaymentTypestringNoOptional. Payment type for the selected gateway, such as card, wallet, etc.
manualPaymentbooleanNoOptional. If true, do not create an automatic payment for the update invoice; the invoice will be created in open status for manual collection.
metadataobjectNoOptional. Custom metadata map that will be stored on the update invoice and subscription pending update record.
newPlanIdintegerYesRequired. Target plan ID to switch the subscription to.
paymentUIModestringNoOptional. Checkout UI mode: hosted | embedded | custom. Default is hosted.
productDatastringNo
prorationDateintegerNoOptional. UTC timestamp at which proration should start when effectImmediate = 1. Defaults to current time if not provided.
quantityintegerYesRequired. Target quantity for the subscription after update.
returnUrlstringNoOptional. URL to redirect the customer to after the update is completed or payment succeeds.
subscriptionIdstringNoOptional. 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.
taxPercentageintegerNoOptional. External tax percentage override for the update invoice, in basis points (e.g. 1000 = 10%%). Overrides the subscription taxPercentage when provided.
userIdintegerNoOptional. 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

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

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.
FieldTypeDescription
codeintegerResponse code. 0 = success
dataobjectResponse payload
data.actionobject
data.invoiceIdstringID of the invoice generated by this update (proration or next-period invoice, depending on effectImmediate).
data.linkstringHosted payment or invoice link. When paid=false and an invoice exists, redirect the customer to this link to complete payment.
data.notestringAdditional message describing the update result, used for internal or merchant-facing explanations.
data.paidbooleanWhether the update invoice has been successfully paid at the time of response.
data.paymentIdstringID of the payment created for the update invoice, if any.
data.subscriptionPendingUpdateobject
messagestringHuman-readable message
requestIdstringRequest ID for support

​
Error handling

HTTP statusMeaning
400Bad request — invalid or missing parameters. Check message in the body.
401Unauthorized — missing or invalid API key.
404Not found — invalid path or resource.
500Server error — retry with backoff.
When code in the response body is non-zero, check message for details. Use requestId when contacting support.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
newPlanId
integer<int64>
required

Required. Target plan ID to switch the subscription to.

​
quantity
integer<int64>
required

Required. Target quantity for the subscription after update.

​
addonParams
object[]

Optional. Target addon configuration after the update.

​
applyPromoCredit
boolean<bool>

Optional. Whether to apply available promo credit when creating the update invoice.

​
applyPromoCreditAmount
integer<*int64>

Optional. Maximum promo credit amount to apply. If omitted and applyPromoCredit is true, the system auto-computes the usable amount.

​
cancelUrl
string<string>

Optional. URL to redirect the customer to when the customer cancels or the update payment fails.

​
confirmCurrency
string<string>

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<int64>

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<*string>

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
object
​
discountCode
string<string>

Optional. Discount or coupon code applied to this update. Overrides the subscription's recurring discount for this invoice.

​
effectImmediate
integer<int>

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<*int64>

Optional. Gateway ID to be used for the invoice generated by this update. If omitted, the subscription's current gateway is used.

​
gatewayPaymentType
string<string>

Optional. Payment type for the selected gateway, such as card, wallet, etc.

​
manualPayment
boolean<bool>

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

Optional. Custom metadata map that will be stored on the update invoice and subscription pending update record.

​
paymentUIMode
string<string>

Optional. Checkout UI mode: hosted | embedded | custom. Default is hosted.

​
productData
object
​
prorationDate
integer<*int64>

Optional. UTC timestamp at which proration should start when effectImmediate = 1. Defaults to current time if not provided.

​
returnUrl
string<string>

Optional. URL to redirect the customer to after the update is completed or payment succeeds.

​
subscriptionId
string<string>

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<*int64>

Optional. External tax percentage override for the update invoice, in basis points (e.g. 1000 = 10%%). Overrides the subscription taxPercentage when provided.

​
userId
integer<int64>

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.

Response

200 - application/json
​
code
integer<int>
​
data
object
​
merchantId
integer<int64>
​
message
string<string>
​
redirect
string<string>
​
requestId
string<string>