This endpoint returns a paginated list of promotions. You can filter by status, type, validity dates, and more.
Authentication
This endpoint requires a valid API key with promotions:read permissions.
Authorization: Bearer YOUR_API_KEY
Query Parameters
Number of promotions to return (1-100)
Number of promotions to skip
Filter by status: “active”, “scheduled”, “paused”, “expired”
Filter by promotion type: “percentage”, “fixed_amount”, “bogo”, “tiered”, “bundle”, “free_shipping”
Search by promotion code (partial match)
Filter promotions active on a specific date (ISO 8601)
Filter by eligible customer segment
sort_by
string
default:"created_at"
Sort by field: “created_at”, “start_date”, “end_date”, “priority”, “usage_count”
Sort order: “asc” or “desc”
Response
Returns a paginated list of promotion objects.
curl --location 'https://api.stateset.com/v1/promotions?status=active&limit=20' \
--header 'Authorization: Bearer YOUR_API_KEY'
{
"object": "list",
"data": [
{
"id": "promo_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
"object": "promotion",
"name": "Summer Sale 2024",
"code": "SUMMER20",
"description": "Get 20% off on all summer collection items",
"type": "percentage",
"value": {
"amount": 20,
"max_discount": 10000
},
"status": "active",
"validity": {
"start_date": "2024-06-01T00:00:00Z",
"end_date": "2024-08-31T23:59:59Z",
"is_active": true
},
"conditions": {
"used_count": 245,
"max_uses_total": 1000
},
"created_at": "2024-01-20T10:00:00Z"
},
{
"id": "promo_1234f083-bb2d-54d6-bg6d-1b0e3gd75f41",
"object": "promotion",
"name": "First Time Buyer",
"code": "WELCOME10",
"description": "10% off for new customers",
"type": "percentage",
"value": {
"amount": 10
},
"status": "active",
"validity": {
"start_date": "2024-01-01T00:00:00Z",
"end_date": null,
"is_active": true
},
"conditions": {
"used_count": 1523,
"max_uses_per_customer": 1
},
"created_at": "2024-01-01T00:00:00Z"
}
],
"has_more": true,
"total_count": 42,
"url": "/v1/promotions"
}
