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.
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.
Use Case
A travel agency selling Viking cruises through the marketplace can display:
- Base prices from Viking’s inventory
- Provider offers like “10% off Mediterranean cruises between June-August”
- 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:
- Pulls offer data from the provider’s API
- Maps provider-specific offer structures to Voyant’s unified schema
- Stores the raw provider payload for debugging
- Updates offer status based on validity dates
Offers are synced automatically. You don’t need to manually import or manage them.
Just connect to a provider and their offers will appear.
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 |
- 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:
// 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
Provider offers are applied by the provider at checkout, not by Voyant.
Display the original price and the offer discount separately to maintain transparency.
- Display the base price from the provider
- Show applicable offers and their discounts
- Show the final price (calculated by the provider)
- Include a “Provider Offer Applied” badge
- 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 othersexclusiveOfferIds: 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 |
Best Practices
- Always show validity dates - Help customers understand offer deadlines
- Display terms clearly - Link to full terms and conditions
- Highlight urgency - Use countdown timers for expiring offers
- Filter by status - Only show
active offers to customers
- Check combinability - Don’t suggest stacking exclusive offers
- Cache appropriately - Offers change less frequently than prices
