Skip to main content

Method

GET /v1/marketplace/offers Requires the catalog:read scope and workspace context.

Query Parameters

providerId
string
Filter offers to a specific provider ID.
productId
string
Filter offers applicable to a specific marketplace product. Returns offers where scope is all, scope is product with no specific products, or applicableProductIds contains this product.
departureId
string
Filter offers applicable to a specific departure/sailing. Returns offers where scope is all, scope is departure with no specific departures, or applicableDepartureIds contains this departure.
status
string
Filter by offer status: active, scheduled, expired, or disabled.
type
string
Filter by offer type: percentage, fixed_amount, upgrade, addon, bundle, early_bird, or last_minute.
scope
string
Filter by offer scope: product, departure, cabin_category, room_type, region, or all.
Search offers by name.
page
integer
default:"1"
Page number for pagination.
limit
integer
default:"20"
Number of items per page (max 100).

Headers

Authorization
string
required
Bearer token (e.g. Authorization: Bearer YOUR_API_KEY)
curl "https://api.voyantcloud.com/v1/marketplace/offers?status=active&type=percentage" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "data": [
    {
      "id": "offr_abc123",
      "providerId": "prov_viking",
      "externalOfferId": "VIKING-SUMMER-2024",
      "name": "Summer Mediterranean Savings",
      "description": "Save 10% on Mediterranean cruises this summer",
      "termsAndConditions": "Valid for new bookings only. Cannot be combined with other offers.",
      "type": "percentage",
      "scope": "region",
      "value": "10",
      "currency": null,
      "validFrom": "2024-06-01T00:00:00Z",
      "validTo": "2024-08-31T23:59:59Z",
      "bookByDate": "2024-07-31T23:59:59Z",
      "travelFrom": "2024-06-01T00:00:00Z",
      "travelTo": "2024-09-30T23:59:59Z",
      "applicableProductIds": [],
      "applicableDepartureIds": [],
      "applicableCabinCategories": [],
      "applicableRoomTypes": [],
      "applicableRegions": ["mediterranean", "aegean"],
      "status": "active",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "provider": {
        "id": "prov_viking",
        "kind": "cruise",
        "displayName": "Viking Cruises",
        "logoUrl": "https://assets.example.com/viking-logo.png"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3
  }
}

Offer Types

TypeDescription
percentagePercentage discount (e.g., “10% off”)
fixed_amountFixed currency amount off (e.g., “$500 off”)
upgradeFree upgrade (e.g., “Free cabin upgrade”)
addonFree addon (e.g., “Free shore excursion”)
bundleBundle discount
early_birdEarly booking discount
last_minuteLast minute discount

Offer Scopes

ScopeDescription
productApplies to specific products
departureApplies to specific departures/sailings
cabin_categoryApplies to specific cabin categories
room_typeApplies to specific room types
regionApplies to specific destinations/regions
allApplies to all eligible items
Only offers from providers your workspace has an active connection to will be returned. If you don’t see expected offers, verify your provider connections are active.