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

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

curl "https://api.voyantcloud.com/v1/marketplace/products/mp_prod_viking_med/offers" \
  -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",
      "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.