GET
/
v1
/
promotions
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"
}
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

​
limit
integer
default:"10"
Number of promotions to return (1-100)
​
offset
integer
default:"0"
Number of promotions to skip
​
status
string
Filter by status: “active”, “scheduled”, “paused”, “expired”
​
type
string
Filter by promotion type: “percentage”, “fixed_amount”, “bogo”, “tiered”, “bundle”, “free_shipping”
​
code
string
Search by promotion code (partial match)
​
active_on
string
Filter promotions active on a specific date (ISO 8601)
​
customer_segment
string
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
string
default:"desc"
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"
}