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.

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:

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

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

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:

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

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