> ## 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.

# Marketplace Provider Offers

> Understanding promotional offers from marketplace providers and how to display them to your customers.

## Overview

Provider offers are promotional discounts and incentives created by external providers (cruise lines, tour operators, hotels) that are synced to the Voyant platform. Unlike workspace promotions which you control, provider offers are read-only and managed by the providers themselves.

<Note>
  Provider offers are distinct from **Workspace Promotions** (promo codes and vouchers created in your Marketing settings). Provider offers come from external suppliers and are automatically synced.
</Note>

## Use Case

A travel agency selling Viking cruises through the marketplace can display:

1. **Base prices** from Viking's inventory
2. **Provider offers** like "10% off Mediterranean cruises between June-August"
3. **Commission earned** on sales

This creates a compelling customer experience by surfacing all available discounts automatically.

## Offer Types

| Type           | Description              | Example                         |
| -------------- | ------------------------ | ------------------------------- |
| `percentage`   | Percentage discount      | "10% off Mediterranean cruises" |
| `fixed_amount` | Fixed currency amount    | "\$500 off your booking"        |
| `upgrade`      | Free category upgrade    | "Free cabin upgrade"            |
| `addon`        | Complimentary extra      | "Free shore excursion included" |
| `bundle`       | Package discount         | "Air + hotel bundle savings"    |
| `early_bird`   | Advance booking discount | "Book 6 months ahead, save 15%" |
| `last_minute`  | Short-notice discount    | "Sail in 30 days, save 20%"     |

## Offer Scopes

Offers can be targeted at different levels:

| Scope            | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `product`        | Applies to specific products                             |
| `departure`      | Applies to specific sailings/departures                  |
| `cabin_category` | Applies to certain cabin types                           |
| `room_type`      | Applies to certain room types                            |
| `region`         | Applies to destinations (e.g., Mediterranean, Caribbean) |
| `all`            | Applies to all eligible items from the provider          |

## How Offers Are Synced

Provider offers are automatically synced from connected providers. The sync process:

1. Pulls offer data from the provider's API
2. Maps provider-specific offer structures to Voyant's unified schema
3. Stores the raw provider payload for debugging
4. Updates offer status based on validity dates

<Tip>
  Offers are synced automatically. You don't need to manually import or manage them.
  Just connect to a provider and their offers will appear.
</Tip>

## Validity Dates

Provider offers have multiple date constraints:

| Field                     | Description                         |
| ------------------------- | ----------------------------------- |
| `validFrom` / `validTo`   | When the offer is active            |
| `bookByDate`              | Customer must book before this date |
| `travelFrom` / `travelTo` | Travel dates the offer applies to   |

An offer is only applicable when:

* Current date is within `validFrom` → `validTo`
* Booking date is before `bookByDate` (if specified)
* Travel date is within `travelFrom` → `travelTo` (if specified)

## Displaying Offers

### On Product Listings

When displaying a product card, show applicable offer badges:

```typescript theme={null}
// Fetch offers for a product
const response = await fetch(
  `/api/marketplace/products/${productId}/offers`
)
const { data: offers } = await response.json()

// Display active offers
offers.forEach(offer => {
  if (offer.type === 'percentage') {
    console.log(`${offer.value}% off - ${offer.name}`)
  } else if (offer.type === 'fixed_amount') {
    console.log(`$${offer.value} off - ${offer.name}`)
  }
})
```

### On Product Detail Pages

Show full offer details including:

* Offer name and description
* Discount value
* Validity period
* Applicable products/cabins/regions
* Terms and conditions

## Provider-Applied Offers

<Warning>
  Provider offers are applied by the provider at checkout, not by Voyant.
  Display the original price and the offer discount separately to maintain transparency.
</Warning>

When a customer books:

1. Display the base price from the provider
2. Show applicable offers and their discounts
3. Show the final price (calculated by the provider)
4. Include a "Provider Offer Applied" badge
5. Link to the offer's terms and conditions

## Combinability

Some offers can be combined with others, while some are mutually exclusive:

* `combinableWithOtherOffers`: Whether the offer can stack with others
* `exclusiveOfferIds`: List of offers that cannot be used together

Always check these fields before displaying multiple offers as potentially stackable.

## API Endpoints

| Endpoint                                         | Description                |
| ------------------------------------------------ | -------------------------- |
| `GET /v1/marketplace/offers`                     | List all accessible offers |
| `GET /v1/marketplace/offers/:id`                 | Get offer details          |
| `GET /v1/marketplace/products/:productId/offers` | Get offers for a product   |

See the [API Reference](/api-reference/marketplace/offers/list) for full documentation.

## Best Practices

1. **Always show validity dates** - Help customers understand offer deadlines
2. **Display terms clearly** - Link to full terms and conditions
3. **Highlight urgency** - Use countdown timers for expiring offers
4. **Filter by status** - Only show `active` offers to customers
5. **Check combinability** - Don't suggest stacking exclusive offers
6. **Cache appropriately** - Offers change less frequently than prices