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>"
}

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>