Skip to main content
POST
Create Subscription

Endpoint Overview

POST https://api.unibee.dev/merchant/subscription/create_submit Create Subscription

Authorization

All UniBee Merchant API requests require authentication via API key.

Parameters

Parameters for this endpoint are listed below. The schema is also shown in the Try it panel.

Request body


Request examples

cURL

Sandbox


Response

Success responses return a JSON envelope with code, data, message, redirect, and requestId. code 0 indicates success.

Error handling

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
planId
integer<int64>
required

Required. ID of the subscription plan to be created.

addonParams
object[]

Optional. List of addon plan parameters to be attached to this subscription.

allowMultipleActiveSubscription
boolean<bool>

Optional. If true, skip the 'one active subscription per user per product' check, allowing the user to hold multiple active subscriptions under the same product. Merchant is responsible for billing in this case.

applyPromoCredit
boolean<bool>

Optional. Whether to apply available promo credit when creating the first 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 user to when the user cancels or the payment fails.

confirmCurrency
string<string>

Optional. When provided, represents the expected currency code for the first invoice and must match the value returned from preview, otherwise the request is rejected.

confirmTotalAmount
integer<int64>

Optional. When provided, represents the expected total amount (in minor units) for the first invoice and must match the value returned from preview, otherwise the request is rejected.

currency
string<string>

Optional. Currency code for charging (e.g. USD, EUR). If empty, plan default currency is used.

discount
object
discountCode
string<string>

Optional. Discount or coupon code to be applied to this subscription creation.

email
string<string>

Optional. End-user email. One of (ExternalUserId & Email), UserId or User object must be provided to identify the user.

externalUserId
string<string>

Optional. Merchant-side unique user identifier. Used together with email when UserId is not provided.

freeInInitialPeriod
boolean<*bool>

Optional. If true, the first billing period is treated as free or trial. This has higher priority than trialEnd.

freeTimeEnd
integer<*int64>

Optional. Custom free period end time when freeInInitialPeriod is true, as UTC timestamp (seconds). Has higher priority than trialEnd and can shorten or extend the default first-period-free behavior.

gatewayId
integer<*int64>

Optional. Payment gateway ID used to charge the first invoice of this subscription.

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 created invoice and subscription.

paymentMethodId
string<string>

Optional. Existing payment method ID to be used for charging the first invoice.

paymentUIMode
string<string>

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

productData
object
quantity
integer<int64>

Optional. Number of units for the plan. Defaults to 1 if not specified.

returnUrl
string<string>

Optional. URL to redirect the user to after successful subscription creation or payment completion.

splitPayment
boolean<bool>

Optional. If true, always use split payment mode: create a hosted invoice link without attempting automatic payment. If false, the system will try automatic payment first and may still switch to split payment based on gateway response and risk control.

startIncomplete
boolean<bool>

Optional. If true, the subscription starts in incomplete status (now pay later): invoice is created and the subscription becomes active temporarily until paid or expired.

subscriptionStartTime
integer<int64>

Optional. Custom subscription first period start time as UTC timestamp (seconds). If set, the first billing period starts from this time instead of current time. Not supported with trial, free initial period or multi-trial plans.

taxPercentage
integer<*int64>

Optional. External tax percentage override, in basis points (e.g. 1000 = 10%%). Overrides subscription-level taxPercentage when provided.

trialEnd
integer<int64>

Optional. Custom trial end time as UTC timestamp (seconds). If greater than now, it overrides the plan default trial configuration.

user
object
userId
integer<int64>

Optional. Internal UniBee user ID. If provided, it must be consistent with email/user when they are also provided.

vatCountryCode
string<string>

Optional. ISO country code for VAT calculation. If provided together with vatNumber, they must be consistent.

vatNumber
string<string>

Optional. Customer VAT number used for VAT validation and tax calculation.

Response

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