Skip to main content
POST
/
merchant
/
subscription
/
renew_preview
Renew Subscription Preview
curl --request POST \
  --url https://api.unibee.dev/merchant/subscription/renew_preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "applyPromoCredit": true,
  "applyPromoCreditAmount": 123,
  "discount": {
    "cycleLimit": 123,
    "discountAmount": 123,
    "discountPercentage": 123,
    "endTime": 123,
    "metadata": {},
    "recurring": true
  },
  "discountCode": "<string>",
  "gatewayId": 123,
  "gatewayPaymentType": "<string>",
  "metadata": {},
  "productData": {
    "description": "<string>",
    "name": "<string>"
  },
  "productId": 123,
  "subscriptionId": "<string>",
  "taxPercentage": 123,
  "userId": 123
}
'
{
  "code": 123,
  "data": {
    "applyPromoCredit": true,
    "currency": "<string>",
    "discountAmount": 123,
    "invoice": {
      "PaymentMethodId": "<string>",
      "autoCharge": true,
      "billingCycleAnchor": 123,
      "bizType": 123,
      "countryCode": "<string>",
      "createFrom": "<string>",
      "creditAccount": {
        "amount": 123,
        "createTime": 123,
        "currency": "<string>",
        "currencyAmount": 123,
        "exchangeRate": 123,
        "id": 123,
        "payoutEnable": 123,
        "rechargeEnable": 123,
        "totalDecrementAmount": 123,
        "totalIncrementAmount": 123,
        "type": 123,
        "userId": 123
      },
      "creditPayout": {
        "creditAmount": 123,
        "currencyAmount": 123,
        "exchangeRate": 123
      },
      "cryptoAmount": 123,
      "cryptoCurrency": "<string>",
      "currency": "<string>",
      "data": "<string>",
      "dayUtilDue": 123,
      "discount": {
        "advance": true,
        "billingType": 123,
        "code": "<string>",
        "createTime": 123,
        "currency": "<string>",
        "cycleLimit": 123,
        "discountAmount": 123,
        "discountPercentage": 123,
        "discountType": 123,
        "endTime": 123,
        "id": 123,
        "isDeleted": 123,
        "merchantId": 123,
        "metadata": {},
        "name": "<string>",
        "planApplyGroup": {
          "currency": [
            "<string>"
          ],
          "groupPlanIntervalSelector": [
            {
              "intervalCount": 123,
              "intervalUnit": "<string>"
            }
          ],
          "type": [
            123
          ]
        },
        "planApplyType": 123,
        "planIds": [
          123
        ],
        "quantity": 123,
        "startTime": 123,
        "status": 123,
        "upgradeLongerOnly": true,
        "upgradeOnly": true,
        "userLimit": 123,
        "userScope": 123
      },
      "discountAmount": 123,
      "discountCode": "<string>",
      "finishTime": 123,
      "gatewayId": 123,
      "id": 123,
      "invoiceId": "<string>",
      "invoiceName": "<string>",
      "lines": [
        {
          "amount": 123,
          "amountExcludingTax": 123,
          "currency": "<string>",
          "description": "<string>",
          "discountAmount": 123,
          "discountCode": "<string>",
          "fromAddress": {
            "address": "<string>",
            "city": "<string>",
            "countryCode": "<string>",
            "state": "<string>",
            "verified": true,
            "zipCode": "<string>"
          },
          "lineId": "<string>",
          "metricCharge": {
            "metricId": 123,
            "CurrentUsedValue": 123,
            "chargePricing": {
              "chargeType": 123,
              "graduatedAmounts": [
                {
                  "endValue": 123,
                  "flatAmount": 123,
                  "perAmount": 123,
                  "startValue": 123
                }
              ],
              "metricId": 123,
              "standardAmount": 123,
              "standardStartValue": 123
            },
            "description": "<string>",
            "lines": [
              {
                "amount": 123,
                "flatAmount": 123,
                "quantity": 123,
                "step": "<string>",
                "unitAmount": 123
              }
            ],
            "maxEventId": 123,
            "minEventId": 123,
            "name": "<string>",
            "totalChargeAmount": 123
          },
          "name": "<string>",
          "nexusAddresses": [
            {
              "address": "<string>",
              "city": "<string>",
              "countryCode": "<string>",
              "state": "<string>",
              "verified": true,
              "zipCode": "<string>"
            }
          ],
          "originAmount": 123,
          "originUnitAmountExcludeTax": 123,
          "pdfDescription": "<string>",
          "periodEnd": 123,
          "periodStart": 123,
          "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>"
              }
            }
          },
          "planMetricChargeConfigs": [
            {
              "chargeType": 123,
              "metricCode": "<string>",
              "metricId": 123,
              "metricName": "<string>",
              "metricType": 123,
              "standardAmount": 123,
              "standardStartValue": 123
            }
          ],
          "planMetricLimitConfigs": [
            {
              "metricCode": "<string>",
              "metricId": 123,
              "metricLimit": 123,
              "metricName": "<string>",
              "metricType": 123
            }
          ],
          "proration": true,
          "prorationDate": 123,
          "prorationScale": 123,
          "quantity": 123,
          "tax": 123,
          "taxCode": "<string>",
          "taxPercentage": 123,
          "toAddress": {
            "address": "<string>",
            "city": "<string>",
            "countryCode": "<string>",
            "state": "<string>",
            "verified": true,
            "zipCode": "<string>"
          },
          "unitAmountExcludingTax": 123,
          "ustaxAlert": "<string>"
        }
      ],
      "link": "<string>",
      "metadata": {},
      "originAmount": 123,
      "partialCreditPaidAmount": 123,
      "paymentId": "<string>",
      "paymentLink": "<string>",
      "paymentType": "<string>",
      "periodEnd": 123,
      "periodStart": 123,
      "planSnapshot": {
        "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
          }
        ],
        "autoCharge": true,
        "chargeType": 123,
        "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>"
            }
          }
        },
        "previousAddons": [
          {
            "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
          }
        ],
        "previousPlan": {
          "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>"
            }
          }
        }
      },
      "productName": "<string>",
      "promoCreditAccount": {
        "amount": 123,
        "createTime": 123,
        "currency": "<string>",
        "currencyAmount": 123,
        "exchangeRate": 123,
        "id": 123,
        "payoutEnable": 123,
        "rechargeEnable": 123,
        "totalDecrementAmount": 123,
        "totalIncrementAmount": 123,
        "type": 123,
        "userId": 123
      },
      "promoCreditDiscountAmount": 123,
      "promoCreditPayout": {
        "creditAmount": 123,
        "currencyAmount": 123,
        "exchangeRate": 123
      },
      "promoCreditTransaction": {
        "accountType": 123,
        "bizId": "<string>",
        "by": "<string>",
        "createTime": 123,
        "creditAmountAfter": 123,
        "creditAmountBefore": 123,
        "creditId": 123,
        "currency": "<string>",
        "deltaAmount": 123,
        "deltaCurrencyAmount": 123,
        "description": "<string>",
        "exchangeRate": 123,
        "id": 123,
        "invoiceId": "<string>",
        "merchantId": 123,
        "name": "<string>",
        "transactionId": "<string>",
        "transactionType": 123,
        "userId": 123
      },
      "prorationDate": 123,
      "prorationScale": 123,
      "refundId": "<string>",
      "sendNote": "<string>",
      "sendStatus": 123,
      "status": 123,
      "subscriptionAmount": 123,
      "subscriptionAmountExcludingTax": 123,
      "subscriptionId": "<string>",
      "taxAmount": 123,
      "taxPercentage": 123,
      "totalAmount": 123,
      "totalAmountExcludingTax": 123,
      "trialEnd": 123,
      "userId": 123,
      "userMetricChargeForInvoice": {
        "meteredChargeStats": [
          {
            "metricId": 123,
            "CurrentUsedValue": 123,
            "chargePricing": {
              "chargeType": 123,
              "graduatedAmounts": [
                {
                  "endValue": 123,
                  "flatAmount": 123,
                  "perAmount": 123,
                  "startValue": 123
                }
              ],
              "metricId": 123,
              "standardAmount": 123,
              "standardStartValue": 123
            },
            "description": "<string>",
            "lines": [
              {
                "amount": 123,
                "flatAmount": 123,
                "quantity": 123,
                "step": "<string>",
                "unitAmount": 123
              }
            ],
            "maxEventId": 123,
            "minEventId": 123,
            "name": "<string>",
            "totalChargeAmount": 123
          }
        ],
        "recurringChargeStats": [
          {
            "metricId": 123,
            "CurrentUsedValue": 123,
            "chargePricing": {
              "chargeType": 123,
              "graduatedAmounts": [
                {
                  "endValue": 123,
                  "flatAmount": 123,
                  "perAmount": 123,
                  "startValue": 123
                }
              ],
              "metricId": 123,
              "standardAmount": 123,
              "standardStartValue": 123
            },
            "description": "<string>",
            "lines": [
              {
                "amount": 123,
                "flatAmount": 123,
                "quantity": 123,
                "step": "<string>",
                "unitAmount": 123
              }
            ],
            "maxEventId": 123,
            "minEventId": 123,
            "name": "<string>",
            "totalChargeAmount": 123
          }
        ]
      },
      "vatNumber": "<string>"
    },
    "originAmount": 123,
    "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>"
    },
    "taxAmount": 123,
    "totalAmount": 123
  },
  "merchantId": 123,
  "message": "<string>",
  "redirect": "<string>",
  "requestId": "<string>"
}

​
Endpoint Overview

POST https://api.unibee.dev/merchant/subscription/renew_preview Preview renew invoice of an existing 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
applyPromoCreditbooleanNoOptional. Whether to apply available promo credit to this renewal invoice.
applyPromoCreditAmountintegerNoOptional. Maximum promo credit amount to apply. If omitted and applyPromoCredit is true, the system auto-computes the usable amount.
discountstringNo
discountCodestringNoOptional. Discount or coupon code applied only to this renewal. Overrides the subscription’s recurring discount for this invoice.
gatewayIdintegerNoOptional. Payment gateway ID used for the renewal invoice. If omitted, the subscription’s original gateway configuration is used.
gatewayPaymentTypestringNoOptional. Payment type for the selected gateway, such as card, wallet, etc.
metadataobjectNoOptional. Custom metadata map that will be stored on the renewal invoice and subscription timeline.
productDatastringNo
productIdintegerNoOptional. 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.
subscriptionIdstringNoOptional. 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.
taxPercentageintegerNoOptional. External tax percentage override for the renewal invoice, in basis points (e.g. 1000 = 10%%). Overrides the subscription taxPercentage when provided.
userIdintegerNoOptional. 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_preview" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "applyPromoCredit": false,
  "applyPromoCreditAmount": 0,
  "discount": "",
  "discountCode": "",
  "gatewayId": 0,
  "gatewayPaymentType": "",
  "metadata": {},
  "productData": "",
  "productId": 0,
  "subscriptionId": "id_example",
  "taxPercentage": 0,
  "userId": 0
}'

​
Sandbox

curl -X POST "https://api-sandbox.unibee.top/merchant/subscription/renew_preview" \
  -H "Authorization: Bearer YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "applyPromoCredit": false,
  "applyPromoCreditAmount": 0,
  "discount": "",
  "discountCode": "",
  "gatewayId": 0,
  "gatewayPaymentType": "",
  "metadata": {},
  "productData": "",
  "productId": 0,
  "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.applyPromoCreditbooleanWhether promo credit is effectively applied in this renew preview.
data.currencystringCurrency used for the renew preview.
data.discountAmountintegerTotal discount amount applied to the renew invoice, including promo credit if applicable.
data.invoiceobject
data.originAmountintegerOriginal invoice amount before discounts and promo credits for the renew, in minor units.
data.subscriptionobject
data.taxAmountintegerTotal tax amount applied to the renew invoice, in minor units.
data.totalAmountintegerFinal payable amount for the renew invoice, including tax and after discounts, in minor units.
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

Preview renew invoice of an existing subscription.

​
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.

​
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.

​
metadata
object

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

​
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.

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