Skip to main content
POST
Create Subscription Preview

Endpoint Overview

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

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

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 to this preview calculation.

applyPromoCreditAmount
integer<*int64>

Optional. Maximum promo credit amount to apply. If omitted and applyPromoCredit is true, the system auto-computes the usable amount.

currency
string<string>

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

discountCode
string<string>

Optional. Discount or coupon code applied to this preview.

email
string<string>

Optional. End-user email. Required when creating a new user via ExternalUserId&Email if userId is not provided.

externalUserId
string<string>

Optional. Merchant-side unique user identifier. Use together with email when userId is not provided.

freeInInitialPeriod
boolean<*bool>

Optional. If true, the first billing period is treated as free or trial, taking precedence over trialEnd.

freeTimeEnd
integer<*int64>

Optional. Custom free period end time when freeInInitialPeriod is true, as UTC timestamp (seconds). Can shorten or extend the default first-period-free behavior.

gatewayId
integer<*int64>

Optional. Payment gateway ID to be used for this subscription preview. If omitted, default gateway selection rules apply.

gatewayPaymentType
string<string>

Optional. Payment type for the selected gateway, such as card, wallet, etc.

quantity
integer<int64>

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

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%%). Only available for OpenAPI calls.

trialEnd
integer<int64>

Optional. Custom trial end time as UTC timestamp (seconds). Overrides plan default trial configuration when greater than now.

user
object
userId
integer<int64>

Optional. Internal user ID in UniBee. If provided, it must match the email/user object 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>