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

# Get Product Offers

> Retrieve promotional offers applicable to a specific marketplace product.

## Method

`GET` `/v1/marketplace/products/{productId}/offers`

Requires the `catalog:read` scope and workspace context.

## Path Parameters

<ParamField path="productId" type="string" required>The marketplace product ID.</ParamField>

## Query Parameters

<ParamField query="status" type="string" default="active">Filter by offer status: `active`, `scheduled`, `expired`, or `disabled`.</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/products/mp_prod_viking_med/offers" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const productId = "mp_prod_viking_med"

  const res = await fetch(
    `https://api.voyantcloud.com/v1/marketplace/products/${productId}/offers`,
    {
      headers: { Authorization: `Bearer ${process.env.VOYANT_API_KEY}` },
    }
  )
  const { data } = await res.json()
  ```

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

  product_id = "mp_prod_viking_med"
  resp = requests.get(
    f"https://api.voyantcloud.com/v1/marketplace/products/{product_id}/offers",
    headers={"Authorization": f"Bearer {os.environ['VOYANT_API_KEY']}"},
  )
  offers = resp.json()["data"]
  ```
</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",
        "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",
        "status": "active",
        "createdAt": "2024-01-15T10:30:00Z",
        "provider": {
          "id": "prov_viking",
          "kind": "cruise",
          "displayName": "Viking Cruises"
        }
      },
      {
        "id": "offr_def456",
        "providerId": "prov_viking",
        "externalOfferId": "VIKING-EARLY-BIRD",
        "name": "Early Bird Discount",
        "description": "Book 6 months in advance and save $300 per cabin",
        "type": "fixed_amount",
        "scope": "all",
        "value": "300",
        "currency": "USD",
        "validFrom": null,
        "validTo": null,
        "bookByDate": null,
        "travelFrom": null,
        "travelTo": null,
        "status": "active",
        "createdAt": "2024-01-10T09:00:00Z",
        "provider": {
          "id": "prov_viking",
          "kind": "cruise",
          "displayName": "Viking Cruises"
        }
      }
    ]
  }
  ```
</ResponseExample>

## How Offers Are Matched

An offer is considered applicable to a product if any of the following conditions are met:

1. **Scope is "all"**: The offer applies to all eligible items from the provider
2. **Scope is "product" with no restrictions**: The offer applies broadly to products
3. **Product ID match**: The product ID is included in the offer's `applicableProductIds` array

<Tip>
  Use this endpoint when displaying a product detail page to show customers what promotions
  are currently available. This helps drive conversions by highlighting active discounts.
</Tip>

<Note>
  By default, only `active` offers are returned. Pass `status=scheduled` to see upcoming
  offers that haven't started yet.
</Note>