FAfanvue

Create a promotion

Changed on

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 unless notifyFans is false.

post/promotions

Request

  • Base URL
    https://api.fanvue.com
  • URL
    https://api.fanvue.com/promotions
  • Auth
    OAuth 2
    Authorization code: https://auth.fanvue.com/oauth2/auth
    Token URL: https://auth.fanvue.com/oauth2/token scopes: write:creator

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

notifyFansboolean

Whether eligible fans receive a notification about the new promotion. Defaults to true. Set to false to create the promotion silently, e.g. when re-creating a capped promotion that fans were already notified about.

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

Changes