> ## Documentation Index > Fetch the complete documentation index at: https://voyant.travel/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a promotional offer > Create a promotional offer with a discount, scope, and optional conditions/validity window. ## OpenAPI ````yaml /api-specs/platform-admin.json post /v1/admin/promotions openapi: 3.1.0 info: title: Voyant Admin API version: 1.0.0 description: >- The staff-facing /v1/admin/* REST API exposed by the framework modules in your deployed Voyant app. Authenticate with a staff session or API token. The server URL is your own app domain, not api.voyant.travel. servers: - url: https://{operatorDomain} variables: operatorDomain: default: app.example.com description: The domain of your deployed Voyant operator app. security: - bearerAuth: [] tags: - name: Accommodations description: >- Accommodation sourced-content detail authoring. Mounted at /v1/admin/accommodations. - name: Action ledger description: >- Auditable action log with approvals, delegations, reversals and relay outbox. - name: Bookings description: >- Booking lifecycle, travelers, items, notes, documents and per-booking action-ledger. - name: Catalog description: >- Catalog search and the booking engine (quote, book, drafts, holds, orders) plus live sourced package/cruise pricing, mounted at /v1/admin/catalog. - name: Charters description: >- Yacht charter catalog: products, voyages, suites, schedules, yachts, per-suite and whole-yacht quotes/bookings and MYBA contracts. Mounted at /v1/admin/charters. - name: CRM description: >- Relationships domain: people, organizations, contacts, addresses, notes, documents, activities, custom fields and customer signals. Mounted at /v1/admin/relationships. - name: Cruises description: >- Cruise catalog authoring: cruises, voyage groups, sailings, prices, ships/decks/categories/cabins, enrichment programs, search index and bookings. Mounted at /v1/admin/cruises. - name: Distribution description: >- Sales-channel distribution: channels, contracts, commission rules, product mappings, booking links, inventory allotments, and settlement runs, mounted at /v1/admin/distribution. - name: Finance description: >- Invoices, credit notes, payments, payment schedules, guarantees, payment sessions, supplier invoices, tax reference data, and finance reports (admin surface, mounted at /v1/admin/finance). - name: Invitations description: >- Staff/agent identity records: named contacts, contact points and addresses, including entity-scoped variants. Mounted at /v1/admin/identity. - name: Legal description: >- Contracts, contract templates, signatures, policies, policy versions, policy acceptances, and legal terms (admin surface, mounted at /v1/admin/legal). - name: Notifications description: >- Notification templates, deliveries, reminder rules/stages/channels, reminder runs and document dispatch. Mounted at /v1/admin/notifications. - name: Operations description: >- Operational supply: availability rules/slots, resources/pools, ground transport and facilities. - name: Products description: >- Owned product catalog authoring: products, options, itineraries, media, brochures, types, categories, and destinations, mounted at /v1/admin/products. - name: Promotions description: >- Promotional offers with discount, scope, conditions, and validity windows, mounted at /v1/admin/promotions. - name: Quotes description: >- Sales quotes, quote versions, lines, pipelines and stages plus proposal send/snapshot. Mounted at /v1/admin/quotes and /v1/admin/quote-versions. - name: Settings description: >- Operator-tenant settings: profile, payment instructions, payment defaults and combined operator settings. Mounted at /v1/admin/settings. - name: Storefront description: Operator-facing storefront configuration. Mounted at /v1/admin/storefront. - name: Trips description: >- Multi-component trip envelopes: composition, pricing, reservation, checkout and snapshots. - name: Workflow runs description: Read-only workflow run inspection plus trigger, rerun and resume. paths: /v1/admin/promotions: post: tags: - Promotions summary: Create a promotional offer description: >- Create a promotional offer with a discount, scope, and optional conditions/validity window. operationId: createPromotion requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PromotionsOfferInput' responses: '201': description: Created offer content: application/json: schema: $ref: '#/components/schemas/PromotionsOfferEnvelope' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' x-codeSamples: - lang: bash label: cURL source: |- curl --request POST \ --url https://app.example.com/v1/admin/promotions \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "name": "", "slug": "", "description": "", "discountType": "percentage", "discountPercent": 123, "discountAmountCents": 123, "currency": "", "scope": { "kind": "global", "productIds": [ "" ], "categoryIds": [ "" ], "destinationIds": [ "" ], "marketIds": [ "" ], "audiences": [ "staff" ], "fareCodes": [ "" ], "cabinGradeCodes": [ "" ] }, "conditions": { "minPax": 123, "pastGuestOnly": true, "soloTravelerOnly": true, "childTravelerOnly": true, "familyOnly": true }, "validFrom": "", "validUntil": "", "code": "", "stackable": true, "active": true, "metadata": {} }' - lang: javascript label: Node source: >- const response = await fetch("https://app.example.com/v1/admin/promotions", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": "Bearer " }, body: JSON.stringify({ "name": "", "slug": "", "description": "", "discountType": "percentage", "discountPercent": 123, "discountAmountCents": 123, "currency": "", "scope": { "kind": "global", "productIds": [ "" ], "categoryIds": [ "" ], "destinationIds": [ "" ], "marketIds": [ "" ], "audiences": [ "staff" ], "fareCodes": [ "" ], "cabinGradeCodes": [ "" ] }, "conditions": { "minPax": 123, "pastGuestOnly": true, "soloTravelerOnly": true, "childTravelerOnly": true, "familyOnly": true }, "validFrom": "", "validUntil": "", "code": "", "stackable": true, "active": true, "metadata": {} }), }); const data = await response.json(); - lang: python label: Python source: |- import requests response = requests.post( "https://app.example.com/v1/admin/promotions", headers={ "Authorization": "Bearer " }, json={ "name": "", "slug": "", "description": "", "discountType": "percentage", "discountPercent": 123, "discountAmountCents": 123, "currency": "", "scope": { "kind": "global", "productIds": [ "" ], "categoryIds": [ "" ], "destinationIds": [ "" ], "marketIds": [ "" ], "audiences": [ "staff" ], "fareCodes": [ "" ], "cabinGradeCodes": [ "" ] }, "conditions": { "minPax": 123, "pastGuestOnly": True, "soloTravelerOnly": True, "childTravelerOnly": True, "familyOnly": True }, "validFrom": "", "validUntil": "", "code": "", "stackable": True, "active": True, "metadata": {} } ) data = response.json() components: schemas: PromotionsOfferInput: type: object required: - name - slug - discountType - scope properties: name: type: string minLength: 1 maxLength: 200 slug: type: string minLength: 1 maxLength: 200 pattern: ^[a-z0-9-]+$ description: type: string discountType: type: string enum: - percentage - fixed_amount discountPercent: type: number description: Required when discountType=percentage (>0, <=100) discountAmountCents: type: integer description: Required (with currency) when discountType=fixed_amount currency: type: string description: 3-letter ISO 4217; required with fixed_amount scope: $ref: '#/components/schemas/PromotionsScope' conditions: $ref: '#/components/schemas/PromotionsConditions' validFrom: type: string format: date validUntil: type: string format: date code: type: string minLength: 1 maxLength: 80 pattern: ^[A-Za-z0-9_-]+$ stackable: type: boolean active: type: boolean metadata: type: object additionalProperties: true PromotionsOfferEnvelope: type: object properties: data: $ref: '#/components/schemas/PromotionsOffer' PromotionsScope: type: object description: >- Discriminated union on `kind`: global | products | categories | destinations | markets | audiences | fare_codes | cabin_grades. required: - kind properties: kind: type: string enum: - global - products - categories - destinations - markets - audiences - fare_codes - cabin_grades productIds: type: array items: type: string categoryIds: type: array items: type: string destinationIds: type: array items: type: string marketIds: type: array items: type: string audiences: type: array items: type: string enum: - staff - customer - partner - supplier fareCodes: type: array items: type: string cabinGradeCodes: type: array items: type: string PromotionsConditions: type: object properties: minPax: type: integer pastGuestOnly: type: boolean soloTravelerOnly: type: boolean childTravelerOnly: type: boolean familyOnly: type: boolean PromotionsOffer: type: object properties: id: type: string name: type: string slug: type: string description: type: string nullable: true discountType: type: string enum: - percentage - fixed_amount discountPercent: type: number nullable: true discountAmountCents: type: integer nullable: true currency: type: string nullable: true scope: $ref: '#/components/schemas/PromotionsScope' conditions: $ref: '#/components/schemas/PromotionsConditions' validFrom: type: string format: date nullable: true validUntil: type: string format: date nullable: true code: type: string nullable: true stackable: type: boolean active: type: boolean metadata: type: object additionalProperties: true ApiError: type: object required: - error properties: error: type: string description: Human-readable error message. code: type: string description: >- Stable, machine-readable error code (e.g. invalid_request, unauthorized, forbidden). Absent for unmapped 500s. requestId: type: string description: >- Correlation id for this request. Also returned in the X-Request-Id response header. details: type: object additionalProperties: true description: >- Optional structured context. Validation errors (400) include `issues` and `fields` from the failed schema. responses: BadRequest: description: >- The request was malformed or failed schema validation (`code: invalid_request`). headers: X-Request-Id: description: >- Correlation id for this request, echoed on every response including errors. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ApiError' Unauthorized: description: 'Authentication is missing or invalid (`code: unauthorized`).' headers: X-Request-Id: description: >- Correlation id for this request, echoed on every response including errors. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ApiError' Forbidden: description: >- The caller is authenticated but not permitted on this surface or lacks the required scope (`code: forbidden`). headers: X-Request-Id: description: >- Correlation id for this request, echoed on every response including errors. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ApiError' ServerError: description: >- An unexpected error occurred. The `X-Request-Id` header identifies the failed request. headers: X-Request-Id: description: >- Correlation id for this request, echoed on every response including errors. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: bearerAuth: type: http scheme: bearer description: Staff session or API token issued by your Voyant app. ````