Sign in
latestOpenAPI 3.1.02026-08-08243131.9 MB

c5ddcd5c7e72

Create a promotion

Create a promotional subscription offer: either a first-month discount (discountPercent) or a free trial, never both. For a free trial, set freeTrialDays (1-30), or set freeTrial: true without freeTrialDays for an unlimited (free-forever) trial.

Creating a promotion replaces any existing promotion targeting the same audience group, and eligible fans are notified.

post/promotions

Headers

X-Fanvue-API-Versionstring required
Example:2025-06-26

API version to use for the request

Request body

discountPercentinteger

First-month discount as a percentage of the subscription price. Mutually exclusive with a free trial.

freeTrialboolean

Set to true to offer a free trial. Combine with freeTrialDays for a fixed length, or omit freeTrialDays for an unlimited (free-forever) trial. Mutually exclusive with discountPercent. Passing freeTrialDays alone also implies a free trial.

freeTrialDaysinteger

Length of the free trial in days (1-30). Omit while freeTrial is true for an unlimited (free-forever) trial. Mutually exclusive with discountPercent.

availableToGroup'new_subscribers' | 'expired_subscribers' | 'all' | 'followers' required

Which fans can redeem the promotion: new_subscribers (never subscribed), expired_subscribers, followers, or all

maxUsagesinteger

Maximum number of redemptions. Unlimited when omitted.

endsAtstring date-time

When the promotion stops being redeemable. Never expires when omitted.

messagestring

Optional message shown to fans with the promotion

Response

Promotion created successfully

uuidstring uuid required

Promotion UUID

type'discount' | 'free_trial' required

Whether the promotion is a first-month discount or a free trial

discountPercentinteger nullable required

Discount percentage (null for free-trial promotions)

freeTrialDaysinteger nullable required

Free trial length in days (null for discount promotions)

availableToGroup'new_subscribers' | 'expired_subscribers' | 'all' | 'followers' required

Which fans can redeem the promotion: new_subscribers (never subscribed), expired_subscribers, followers, or all

endsAtstring date-time nullable required

When the promotion expires (null if it never expires)

maxUsagesinteger nullable required

Maximum number of redemptions (null if unlimited)

usedCountinteger required

Number of times the promotion has been redeemed

messagestring nullable required

Message shown to fans with the promotion

createdAtstring date-time required

When the promotion was created