> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Promotions

> List all promotions with filtering and pagination options

<Note>
  This endpoint returns a paginated list of promotions. You can filter by status, type, validity dates, and more.
</Note>

## Authentication

This endpoint requires a valid API key with `promotions:read` permissions.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Query Parameters

<ParamField query="limit" type="integer" default="10">
  Number of promotions to return (1-100)
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of promotions to skip
</ParamField>

<ParamField query="status" type="string">
  Filter by status: "active", "scheduled", "paused", "expired"
</ParamField>

<ParamField query="type" type="string">
  Filter by promotion type: "percentage", "fixed\_amount", "bogo", "tiered", "bundle", "free\_shipping"
</ParamField>

<ParamField query="code" type="string">
  Search by promotion code (partial match)
</ParamField>

<ParamField query="active_on" type="string">
  Filter promotions active on a specific date (ISO 8601)
</ParamField>

<ParamField query="customer_segment" type="string">
  Filter by eligible customer segment
</ParamField>

<ParamField query="sort_by" type="string" default="created_at">
  Sort by field: "created\_at", "start\_date", "end\_date", "priority", "usage\_count"
</ParamField>

<ParamField query="sort_order" type="string" default="desc">
  Sort order: "asc" or "desc"
</ParamField>

### Response

Returns a paginated list of promotion objects.

<RequestExample>
  ```bash cURL theme={null}
  curl --location 'https://api.stateset.com/v1/promotions?status=active&limit=20' \
  --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript Node.js theme={null}
  const promotions = await stateset.promotions.list({
    status: 'active',
    limit: 20
  });
  ```

  ```python Python theme={null}
  promotions = stateset.promotions.list(
    status='active',
    limit=20
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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"
  }
  ```
</ResponseExample>