StateSet API Docs

curl --location 'https://api.stateset.com/api/v1/promotions?status=active&limit=20' \
--header 'Authorization: Bearer YOUR_API_KEY'

const promotions = await stateset.promotions.list({
  status: 'active',
  limit: 20
});

promotions = stateset.promotions.list(
  status='active',
  limit=20
)

{
  "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"
}

GET

api

promotions

curl --location 'https://api.stateset.com/api/v1/promotions?status=active&limit=20' \
--header 'Authorization: Bearer YOUR_API_KEY'

const promotions = await stateset.promotions.list({
  status: 'active',
  limit: 20
});

promotions = stateset.promotions.list(
  status='active',
  limit=20
)

{
  "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

integer

default:"10"

Number of promotions to return (1-100)

integer

default:"0"

Number of promotions to skip

string

Filter by status: “active”, “scheduled”, “paused”, “expired”

string

Filter by promotion type: “percentage”, “fixed_amount”, “bogo”, “tiered”, “bundle”, “free_shipping”

string

Search by promotion code (partial match)

string

Filter promotions active on a specific date (ISO 8601)

string

Filter by eligible customer segment

string

default:"created_at"

Sort by field: “created_at”, “start_date”, “end_date”, “priority”, “usage_count”

string

default:"desc"

Sort order: “asc” or “desc”

Response

Returns a paginated list of promotion objects.

curl --location 'https://api.stateset.com/api/v1/promotions?status=active&limit=20' \
--header 'Authorization: Bearer YOUR_API_KEY'

const promotions = await stateset.promotions.list({
  status: 'active',
  limit: 20
});

promotions = stateset.promotions.list(
  status='active',
  limit=20
)

{
  "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"
}

Calculate Price Get Promotion

StateSet One API

StateSet API v1

Customer Management

Order Management

Checkouts

Returns Management

Warranty Management

Wholesale Management

Inventory Management

ASN Management

Purchase Orders

Manufacturing

Warehouse Operations

CRM

Suppliers

E-commerce

Financial

Fulfillment

Communication

System

StateSet Response API

StateSet Cloud API

StateSet Commerce API

List Promotions

Authentication

Query Parameters

Response

​Authentication

​Query Parameters

​Response

Authentication

Query Parameters

Response