Renew Subscription

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

POST /merchant/subscription/renew

Renew Subscription

cURL

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

200

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

Endpoint Overview

POST https://api.unibee.dev/merchant/subscription/renew

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

---

Authorization

All UniBee Merchant API requests require authentication via API key.

Header	Required	Description
Authorization	Yes	Bearer <your_api_key>
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
applyPromoCredit	boolean	No	Optional. Whether to apply available promo credit to this renewal 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 renewal payment is cancelled or fails.
discount	string	No
discountCode	string	No	Optional. Discount or coupon code applied only to this renewal. Overrides the subscription’s recurring discount for this invoice.
gatewayId	integer	No	Optional. Payment gateway ID used for the renewal invoice. If omitted, the subscription’s original gateway configuration 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 renewal 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 renewal invoice and subscription timeline.
paymentUIMode	string	No	Optional. Checkout UI mode: hosted | embedded | custom. Default is hosted.
productData	string	No
productId	integer	No	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	No	Optional. URL to redirect the customer to after successful renewal or payment completion.
subscriptionId	string	No	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	No	Optional. External tax percentage override for the renewal invoice, in basis points (e.g. 1000 = 10%%). Overrides the subscription taxPercentage when provided.
userId	integer	No	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.

---

Request examples

cURL

curl -X POST "https://api.unibee.dev/merchant/subscription/renew" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "applyPromoCredit": false,
  "applyPromoCreditAmount": 0,
  "cancelUrl": "https://example.com",
  "discount": "",
  "discountCode": "",
  "gatewayId": 0,
  "gatewayPaymentType": "",
  "manualPayment": false,
  "metadata": {},
  "paymentUIMode": "",
  "productData": "",
  "productId": 0,
  "returnUrl": "https://example.com",
  "subscriptionId": "id_example",
  "taxPercentage": 0,
  "userId": 0
}'

Sandbox

curl -X POST "https://api-sandbox.unibee.top/merchant/subscription/renew" \
  -H "Authorization: Bearer YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "applyPromoCredit": false,
  "applyPromoCreditAmount": 0,
  "cancelUrl": "https://example.com",
  "discount": "",
  "discountCode": "",
  "gatewayId": 0,
  "gatewayPaymentType": "",
  "manualPayment": false,
  "metadata": {},
  "paymentUIMode": "",
  "productData": "",
  "productId": 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 renewal invoice generated by this request.
data.link	string	Hosted payment or invoice link. When paid=false, redirect the customer to this link to complete the renewal payment.
data.paid	boolean	Whether the renewal invoice has been successfully paid at the time of response.
data.paymentId	string	ID of the payment created for the renewal invoice, if any.
data.subscription	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.

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

Show child attributes

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.

Show child attributes

paymentUIMode · string<string>

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

productData · object

Show child attributes

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

Show child attributes

merchantId · integer<int64>

message · string<string>

redirect · string<string>

requestId · string<string>