Skip to main content
POST
/
merchant
/
subscription
/
renew
Renew Subscription
curl --request POST \
  --url https://api.unibee.dev/merchant/subscription/renew \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "applyPromoCredit": true,
  "applyPromoCreditAmount": 123,
  "cancelUrl": "<string>",
  "discount": {
    "cycleLimit": 123,
    "discountAmount": 123,
    "discountPercentage": 123,
    "endTime": 123,
    "metadata": {},
    "recurring": true
  },
  "discountCode": "<string>",
  "gatewayId": 123,
  "gatewayPaymentType": "<string>",
  "manualPayment": true,
  "metadata": {},
  "paymentUIMode": "<string>",
  "productData": {
    "description": "<string>",
    "name": "<string>"
  },
  "productId": 123,
  "returnUrl": "<string>",
  "subscriptionId": "<string>",
  "taxPercentage": 123,
  "userId": 123
}
'
{
  "code": 123,
  "data": {
    "action": {},
    "invoiceId": "<string>",
    "link": "<string>",
    "paid": true,
    "paymentId": "<string>",
    "subscription": {
      "addonData": "<string>",
      "amount": 123,
      "billingCycleAnchor": 123,
      "cancelAtPeriodEnd": 123,
      "cancelOrExpireTime": 123,
      "cancelReason": "<string>",
      "countryCode": "<string>",
      "createTime": 123,
      "currency": "<string>",
      "currentPeriodEnd": 123,
      "currentPeriodPaid": 123,
      "currentPeriodStart": 123,
      "defaultPaymentMethodId": "<string>",
      "dunningTime": 123,
      "externalSubscriptionId": "<string>",
      "features": "<string>",
      "firstPaidTime": 123,
      "gasPayer": "<string>",
      "gatewayId": 123,
      "gatewayStatus": "<string>",
      "id": 123,
      "lastUpdateTime": 123,
      "latestInvoiceId": "<string>",
      "link": "<string>",
      "merchantId": 123,
      "metadata": {},
      "originalPeriodEnd": 123,
      "pendingUpdateId": "<string>",
      "planId": 123,
      "productId": 123,
      "quantity": 123,
      "returnUrl": "<string>",
      "status": 123,
      "subscriptionId": "<string>",
      "taskTime": "<string>",
      "taxPercentage": 123,
      "testClock": 123,
      "trialEnd": 123,
      "type": 123,
      "userId": 123,
      "vatNumber": "<string>"
    }
  },
  "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

Manually renew an existing subscription by generating a new recurring invoice and payment.

applyPromoCredit
boolean<*bool>

Optional. Whether to apply available promo credit to this renewal 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 renewal payment is cancelled or fails.

discount
object
discountCode
string<string>

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

gatewayId
integer<*int64>

Optional. Payment gateway ID used for the renewal invoice. If omitted, the subscription's original gateway configuration 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 renewal invoice; the invoice will be created in open status for manual collection.

metadata
object

Optional. Custom metadata map that will be stored on the renewal invoice and subscription timeline.

paymentUIMode
string<string>

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

productData
object
productId
integer<int64>

Optional. Product ID used together with userId when subscriptionId is not specified, to narrow down which subscription to renew. If 0, the system uses its default product selection rules.

returnUrl
string<string>

Optional. URL to redirect the customer to after successful renewal or payment completion.

subscriptionId
string<string>

Optional. SubscriptionId to be renewed. Either subscriptionId or userId must be provided. When subscriptionId is omitted, the system first tries to find the latest active or incomplete subscription for the user (and productId if provided), otherwise falls back to the latest subscription.

taxPercentage
integer<*int64>

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

userId
integer<int64>

Optional. UserId associated with the subscription to renew. Either subscriptionId or userId must be provided. Used to locate the target subscription when subscriptionId is not provided.

Response

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