> ## Documentation Index > Fetch the complete documentation index at: https://api.fanvue.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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. **Required scope** * `write:creator` — Modify creator profiles, settings, and creator-specific data. ## OpenAPI ````yaml /openapi.json post /promotions openapi: 3.1.0 info: title: Fanvue API version: '0.1' servers: [] security: [] paths: /promotions: post: summary: Create a promotion description: >- 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. operationId: createPromotion parameters: - $ref: '#/components/parameters/ApiVersionHeader' requestBody: content: application/json: schema: type: object properties: discountPercent: type: integer minimum: 1 maximum: 100 description: >- First-month discount as a percentage of the subscription price. Mutually exclusive with a free trial. freeTrial: type: boolean description: >- 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: type: integer minimum: 1 maximum: 30 description: >- 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: type: string enum: - new_subscribers - expired_subscribers - all - followers description: >- Which fans can redeem the promotion: new_subscribers (never subscribed), expired_subscribers, followers, or all maxUsages: type: integer minimum: 1 maximum: 1000 description: Maximum number of redemptions. Unlimited when omitted. endsAt: type: string format: date-time description: >- When the promotion stops being redeemable. Never expires when omitted. message: type: string description: Optional message shown to fans with the promotion required: - availableToGroup responses: '201': description: Promotion created successfully content: application/json: schema: type: object properties: uuid: type: string format: uuid description: Promotion UUID type: type: string enum: - discount - free_trial description: >- Whether the promotion is a first-month discount or a free trial discountPercent: type: - integer - 'null' description: Discount percentage (null for free-trial promotions) freeTrialDays: type: - integer - 'null' description: Free trial length in days (null for discount promotions) availableToGroup: type: string enum: - new_subscribers - expired_subscribers - all - followers description: >- Which fans can redeem the promotion: new_subscribers (never subscribed), expired_subscribers, followers, or all endsAt: type: - string - 'null' format: date-time description: When the promotion expires (null if it never expires) maxUsages: type: - integer - 'null' description: Maximum number of redemptions (null if unlimited) usedCount: type: integer description: Number of times the promotion has been redeemed message: type: - string - 'null' description: Message shown to fans with the promotion createdAt: type: string format: date-time description: When the promotion was created required: - uuid - type - discountPercent - freeTrialDays - availableToGroup - endsAt - maxUsages - usedCount - message - createdAt example: uuid: d4e5f6a7-8b9c-4d1e-a2b3-c4d5e6f7a8b9 type: discount discountPercent: 20 freeTrialDays: null availableToGroup: new_subscribers endsAt: '2024-02-15T00:00:00.000Z' maxUsages: 100 usedCount: 12 message: 20% off your first month! createdAt: '2024-01-15T00:00:00.000Z' '400': description: Bad Request - API version not supported OR validation failed content: application/json: schema: oneOf: - $ref: '#/components/schemas/UnsupportedVersionError' - $ref: '#/components/schemas/ValidationError' '401': $ref: '#/components/responses/UnauthorizedResponse' '403': $ref: '#/components/responses/UnauthorizedResponse' '410': $ref: '#/components/responses/SunsetVersionResponse' '429': $ref: '#/components/responses/RateLimitResponse' security: - BearerAuth: - write:creator components: parameters: ApiVersionHeader: name: X-Fanvue-API-Version in: header required: true schema: type: string default: '2025-06-26' example: '2025-06-26' description: API version to use for the request schemas: UnsupportedVersionError: type: object properties: error: type: string message: type: string required: - error - message description: API version not supported ValidationError: type: object properties: errors: type: array items: type: string required: - errors description: Request validation failed responses: UnauthorizedResponse: description: Unauthorized Response content: application/json: schema: type: object properties: error: type: string required: - error SunsetVersionResponse: description: API version no longer supported (sunset) content: application/json: schema: type: object properties: error: type: string message: type: string nextVersion: type: string required: - error - message RateLimitResponse: description: Too many requests - rate limit exceeded headers: Retry-After: description: Number of seconds to wait before retrying the request schema: type: integer X-RateLimit-Limit: description: The maximum number of requests allowed in the current window schema: type: integer X-RateLimit-Remaining: description: The number of requests remaining in the current window schema: type: integer X-RateLimit-Reset: description: The Unix timestamp (seconds) when the rate limit window resets schema: type: integer content: application/json: schema: type: object properties: error: type: string required: - error securitySchemes: BearerAuth: type: oauth2 description: >- 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. flows: authorizationCode: authorizationUrl: https://auth.fanvue.com/oauth2/auth tokenUrl: https://auth.fanvue.com/oauth2/token refreshUrl: https://auth.fanvue.com/oauth2/token scopes: read:self: >- Access your own user profile information, including basic account details and settings. read:chat: >- Read chat conversations, messages, and chat-related data. This includes viewing chat lists and message history. write:chat: >- Create new chats and send messages. This scope is required for any chat-related actions that modify data. read:experience: >- Exchange a fan's experience token for the resolved experience and the fan's identity, so an embedded fan-facing experience can render the right content. write:experience: >- Request that the creator publish or unpublish a fan-facing experience. The app mints a request token; the creator confirms and Fanvue performs the change. read:fan: Access fan-related data and information within the platform. read:post: Read posts, including post details, comments, likes, and tips. write:post: Create, edit, and manage posts and content on behalf of users. read:media: Access media files, images, videos, and other content assets. write:media: >- Upload, modify, and manage media files and content assets. Also required for vault folder management. read:creator: >- Access creator profiles, content, and creator-specific information. write:creator: Modify creator profiles, settings, and creator-specific data. read:insights: >- Access analytics, metrics, and insights data for performance tracking. read:tracking_links: >- Read tracking links and the users associated with them, including per-user tracking metadata. write:tracking_links: Create and delete tracking links. read:agency: Read agency information, including the agency's team members. write:agency: >- Manage agency team members and invites, including inviting new team members and creators. ````