> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voyantcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Promotions Overview

> Create and manage promotional campaigns with discount codes

The Promotions API allows you to create and manage promotional campaigns with discount codes for your booking engine. Promotions support various discount types including percentage off, fixed amounts, and more.

## Key concepts

### Promotions

A promotion defines the discount rules and constraints:

* **Type**: The kind of discount (percentage, fixed amount, BOGO, bundle, tiered, free shipping, gift with purchase)
* **Scope**: What the promotion applies to (all products, specific products, categories, collections, or departures)
* **Value**: The discount amount or percentage
* **Validity period**: When the promotion is active
* **Usage limits**: Maximum total uses or per-customer limits

### Promotion codes

Codes are the actual strings customers enter to redeem a promotion:

* Each promotion can have multiple codes
* Codes can have their own validity periods and usage limits
* Codes are automatically uppercased for case-insensitive matching

## Scopes required

| Endpoint                       | Scope             |
| ------------------------------ | ----------------- |
| List, get, validate            | `marketing:read`  |
| Create, update, delete, redeem | `marketing:write` |

## Promotion types

| Type                 | Description                       |
| -------------------- | --------------------------------- |
| `percentage`         | Percentage discount off the order |
| `fixed_amount`       | Fixed monetary discount           |
| `bogo`               | Buy one get one free              |
| `bundle`             | Bundle discount                   |
| `tiered`             | Tiered pricing based on quantity  |
| `free_shipping`      | Free shipping discount            |
| `gift_with_purchase` | Free gift with purchase           |

## Promotion scopes

| Scope                  | Description                           |
| ---------------------- | ------------------------------------- |
| `all_products`         | Applies to all products               |
| `specific_products`    | Only applies to listed product IDs    |
| `specific_categories`  | Only applies to listed category IDs   |
| `specific_collections` | Only applies to listed collection IDs |
| `specific_departures`  | Only applies to listed departure IDs  |

## Validation flow

When validating a promotion code:

1. **Code lookup**: Find the code and check it's active
2. **Code validity**: Check date range and usage limits
3. **Promotion status**: Verify parent promotion is active
4. **Promotion validity**: Check promotion date range and total usage
5. **Order constraints**: Verify minimum order value, currency, product eligibility
6. **Customer limits**: Check per-customer usage if customer ID provided
7. **Calculate discount**: Return the applicable discount amount