Skip to main content

​
Method

GET /v1/marketplace/products/{productId}/offers Requires the catalog:read scope and workspace context.

​
Path Parameters

​
productId
string
required
The marketplace product ID.

​
Query Parameters

​
status
string
default:"active"
Filter by offer status: active, scheduled, expired, or disabled.

​
Headers

​
Authorization
string
required
Bearer token (e.g. Authorization: Bearer YOUR_API_KEY)
curl "https://api.voyantcloud.com/v1/marketplace/products/mp_prod_viking_med/offers" \
  -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",
      "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"
      }
    }
  ]
}

​
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
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.
By default, only active offers are returned. Pass status=scheduled to see upcoming offers that haven’t started yet.