List Promotions

Retrieve a paginated list of promotions

Authorization · string · required

Bearer token with marketing:read scope

Query parameters

status · string

Filter by status: draft, scheduled, active, paused, expired, archived

type · string

Filter by type: percentage, fixed_amount, bogo, bundle, tiered, free_shipping, gift_with_purchase

scope · string

Filter by scope: all_products, specific_products, specific_categories, specific_collections, specific_departures

limit · integer · default: "50"

Number of results per page (max 100)

offset · integer · default: "0"

Number of results to skip

Response

data.promotions · array

Array of promotion objects

data.meta.total · integer

Total number of promotions matching the filter

data.meta.limit · integer

Number of results per page

data.meta.offset · integer

Number of results skipped

Request

curl -X GET "https://api.voyantcloud.com/v1/promotions?status=active&limit=10" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": {
    "promotions": [
      {
        "id": "promo_abc123",
        "name": "Summer Sale 2024",
        "description": "20% off all summer departures",
        "type": "percentage",
        "scope": "all_products",
        "value": "20",
        "status": "active",
        "currency": "EUR",
        "validFrom": "2024-06-01T00:00:00Z",
        "validTo": "2024-08-31T23:59:59Z",
        "currentTotalUses": 150,
        "maxTotalUses": 1000,
        "createdAt": "2024-05-15T10:30:00Z"
      }
    ],
    "meta": {
      "total": 1,
      "limit": 10,
      "offset": 0
    }
  }
}