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

# 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

<ParamField query="providerId" type="string">Filter offers to a specific provider ID.</ParamField>
<ParamField query="productId" type="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.</ParamField>
<ParamField query="departureId" type="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.</ParamField>
<ParamField query="status" type="string">Filter by offer status: `active`, `scheduled`, `expired`, or `disabled`.</ParamField>
<ParamField query="type" type="string">Filter by offer type: `percentage`, `fixed_amount`, `upgrade`, `addon`, `bundle`, `early_bird`, or `last_minute`.</ParamField>
<ParamField query="scope" type="string">Filter by offer scope: `product`, `departure`, `cabin_category`, `room_type`, `region`, or `all`.</ParamField>
<ParamField query="search" type="string">Search offers by name.</ParamField>
<ParamField query="page" type="integer" default="1">Page number for pagination.</ParamField>
<ParamField query="limit" type="integer" default="20">Number of items per page (max 100).</ParamField>

## Headers

<ParamField header="Authorization" type="string" required>Bearer token (e.g. <code>Authorization: Bearer YOUR\_API\_KEY</code>)</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.voyantcloud.com/v1/marketplace/offers?status=active&type=percentage" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const url = new URL("https://api.voyantcloud.com/v1/marketplace/offers")
  url.searchParams.append("status", "active")
  url.searchParams.append("type", "percentage")

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.VOYANT_API_KEY}` },
  })
  const { data, pagination } = await res.json()
  ```

  ```python Python theme={null}
  import os, requests

  resp = requests.get(
    "https://api.voyantcloud.com/v1/marketplace/offers",
    params={"status": "active", "type": "percentage"},
    headers={"Authorization": f"Bearer {os.environ['VOYANT_API_KEY']}"},
  )
  result = resp.json()
  offers = result["data"]
  pagination = result["pagination"]
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "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
    }
  }
  ```
</ResponseExample>

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

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