List Provider Offers

Retrieve promotional offers from your connected marketplace providers.

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

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

curl "https://api.voyantcloud.com/v1/marketplace/offers?status=active&type=percentage" \
  -H "Authorization: Bearer YOUR_API_KEY"

200 OK

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

Type	Description
percentage	Percentage discount (e.g., “10% off”)
fixed_amount	Fixed currency amount off (e.g., “$500 off”)
upgrade	Free upgrade (e.g., “Free cabin upgrade”)
addon	Free addon (e.g., “Free shore excursion”)
bundle	Bundle discount
early_bird	Early booking discount
last_minute	Last minute discount

Offer Scopes

Scope	Description
product	Applies to specific products
departure	Applies to specific departures/sailings
cabin_category	Applies to specific cabin categories
room_type	Applies to specific room types
region	Applies to specific destinations/regions
all	Applies 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.