> ## 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. # Renew Subscription > Manually renew an existing subscription by generating a new recurring invoice and payment. ## 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 `` | | `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 ```bash theme={null} 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 ```bash theme={null} 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. ## OpenAPI ````yaml post /merchant/subscription/renew 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/renew: post: tags: - Subscription Update summary: Renew Subscription description: >- Manually renew an existing subscription by generating a new recurring invoice and payment. requestBody: content: application/json: schema: $ref: '#/components/schemas/unibee.api.merchant.subscription.RenewReq' 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 renewal invoice generated by this request. format: string properties: {} type: string link: description: >- Hosted payment or invoice link. When paid=false, redirect the customer to this link to complete the renewal payment. format: string properties: {} type: string paid: description: >- Whether the renewal invoice has been successfully paid at the time of response. format: bool properties: {} type: boolean paymentId: description: >- ID of the payment created for the renewal invoice, if any. format: string properties: {} type: string subscription: $ref: '#/components/schemas/unibee.api.bean.Subscription' 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.RenewReq: description: >- Manually renew an existing subscription by generating a new recurring invoice and payment. properties: applyPromoCredit: description: >- Optional. Whether to apply available promo credit to this renewal 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 renewal payment is cancelled or fails. format: string properties: {} type: string discount: $ref: '#/components/schemas/unibee.api.bean.ExternalDiscountParam' discountCode: description: >- Optional. Discount or coupon code applied only to this renewal. Overrides the subscription's recurring discount for this invoice. format: string properties: {} type: string gatewayId: description: >- Optional. Payment gateway ID used for the renewal invoice. If omitted, the subscription's original gateway configuration 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 renewal 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 renewal invoice and subscription timeline. format: map[string]interface {} properties: {} type: object 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' productId: description: >- 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. format: int64 properties: {} type: integer returnUrl: description: >- Optional. URL to redirect the customer to after successful renewal or payment completion. format: string properties: {} type: string subscriptionId: description: >- 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. format: string properties: {} type: string taxPercentage: description: >- Optional. External tax percentage override for the renewal 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 renew. Either subscriptionId or userId must be provided. Used to locate the target subscription when subscriptionId is not provided. format: int64 properties: {} type: integer type: object github.com.gogf.gf.v2.encoding.gjson.Json: properties: {} type: object unibee.api.bean.Subscription: properties: addonData: description: plan addon json data format: string properties: {} type: string amount: description: amount, cent format: int64 properties: {} type: integer billingCycleAnchor: description: billing_cycle_anchor format: int64 properties: {} type: integer cancelAtPeriodEnd: description: whether cancel at period end，0-false | 1-true format: int properties: {} type: integer cancelOrExpireTime: description: >- the cancel or expire time, utc time, 0 if subscription not in cancelled or expired status format: int64 properties: {} type: integer cancelReason: format: string properties: {} type: string countryCode: format: string properties: {} type: string createTime: description: create utc time format: int64 properties: {} type: integer currency: description: currency format: string properties: {} type: string currentPeriodEnd: description: current_period_end, utc time format: int64 properties: {} type: integer currentPeriodPaid: description: current period paid or not, 1-paid, other-the utc time to expire format: int64 properties: {} type: integer currentPeriodStart: description: current_period_start, utc time format: int64 properties: {} type: integer defaultPaymentMethodId: format: string properties: {} type: string dunningTime: description: dunning_time, utc time format: int64 properties: {} type: integer externalSubscriptionId: description: external_subscription_id format: string properties: {} type: string features: description: features format: string properties: {} type: string firstPaidTime: description: first success payment time format: int64 properties: {} type: integer gasPayer: description: who pay the gas, merchant|user format: string properties: {} type: string gatewayId: description: gateway_id format: int64 properties: {} type: integer gatewayStatus: description: >- gateway status，Stripe：https://stripe.com/docs/billing/subscriptions/webhooks Paypal：https://developer.paypal.com/docs/api/subscriptions/v1/#subscriptions_get format: string properties: {} type: string id: format: int64 properties: {} type: integer lastUpdateTime: format: int64 properties: {} type: integer latestInvoiceId: description: latest_invoice_id format: string properties: {} type: string link: 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 originalPeriodEnd: description: original_period_end, utc time format: int64 properties: {} type: integer pendingUpdateId: format: string properties: {} type: string planId: description: plan id format: int64 properties: {} type: integer productId: description: product id format: int64 properties: {} type: integer quantity: description: quantity format: int64 properties: {} type: integer returnUrl: format: string properties: {} type: string status: description: >- status，1-Pending｜2-Active｜3-PendingInActive | 4-Cancel | 5-Expire | 6- Suspend| 7-Incomplete | 8-Processing | 9- Failed format: int properties: {} type: integer subscriptionId: description: subscription id format: string properties: {} type: string taskTime: description: task_time format: '*gtime.Time' properties: {} type: string taxPercentage: description: TaxPercentage，1000 = 10% format: int64 properties: {} type: integer testClock: description: >- test_clock, simulator clock for subscription, if set , sub will out of cronjob controll format: int64 properties: {} type: integer trialEnd: description: trial_end, utc time format: int64 properties: {} type: integer type: description: sub type, 0-gateway sub, 1-unibee sub format: int properties: {} type: integer userId: description: userId format: int64 properties: {} type: integer vatNumber: format: string properties: {} type: string 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 securitySchemes: Authorization: bearerFormat: JWT scheme: bearer type: http ````