Skip to main content
POST
Create a promotion
Required scope
  • write:creator — Modify creator profiles, settings, and creator-specific data.

Authorizations

Authorization
string
header
required

OAuth 2.0 access token, presented as a JWT bearer token in the Authorization header. Obtain a token via the authorization-code flow; the scopes granted to the token determine which operations it may call.

Headers

X-Fanvue-API-Version
string
default:2025-06-26
required

API version to use for the request

Example:

"2025-06-26"

Body

application/json
availableToGroup
enum<string>
required

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

Available options:
new_subscribers,
expired_subscribers,
all,
followers
discountPercent
integer

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

Required range: 1 <= x <= 100
freeTrial
boolean

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.

freeTrialDays
integer

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

Required range: 1 <= x <= 30
maxUsages
integer

Maximum number of redemptions. Unlimited when omitted.

Required range: 1 <= x <= 1000
endsAt
string<date-time>

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

message
string

Optional message shown to fans with the promotion

Response

Promotion created successfully

uuid
string<uuid>
required

Promotion UUID

type
enum<string>
required

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

Available options:
discount,
free_trial
discountPercent
integer | null
required

Discount percentage (null for free-trial promotions)

freeTrialDays
integer | null
required

Free trial length in days (null for discount promotions)

availableToGroup
enum<string>
required

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

Available options:
new_subscribers,
expired_subscribers,
all,
followers
endsAt
string<date-time> | null
required

When the promotion expires (null if it never expires)

maxUsages
integer | null
required

Maximum number of redemptions (null if unlimited)

usedCount
integer
required

Number of times the promotion has been redeemed

message
string | null
required

Message shown to fans with the promotion

createdAt
string<date-time>
required

When the promotion was created