Get Promotion

Retrieve details of a specific promotion

This endpoint retrieves detailed information about a specific promotion, including its current usage statistics and performance metrics.

Authentication

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

Authorization: Bearer YOUR_API_KEY

Path Parameters

id · string · required

The unique identifier of the promotion

Response

Returns the promotion object if found.

cURL

curl --location 'https://api.stateset.com/v1/promotions/promo_0901f083-aa1c-43c5-af5c-0a9d2fc64e30' \
--header 'Authorization: Bearer YOUR_API_KEY'

Response

{
  "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
  },
  "conditions": {
    "min_purchase_amount": 5000,
    "max_uses_total": 1000,
    "max_uses_per_customer": 1,
    "used_count": 245,
    "category_ids": ["cat_summer_2024"],
    "exclude_sale_items": true
  },
  "validity": {
    "start_date": "2024-06-01T00:00:00Z",
    "end_date": "2024-08-31T23:59:59Z",
    "timezone": "America/Los_Angeles",
    "is_active": true,
    "days_remaining": 72
  },
  "stacking": {
    "allowed": false,
    "priority": 1
  },
  "display": {
    "show_in_catalog": true,
    "show_in_cart": true,
    "badge_text": "SUMMER SALE"
  },
  "status": "active",
  "created_at": "2024-01-20T10:00:00Z",
  "updated_at": "2024-06-15T14:30:00Z",
  "created_by": "user_123",
  "performance": {
    "total_orders": 245,
    "total_revenue": 489750,
    "total_discount_given": 97950,
    "conversion_rate": 0.0245,
    "average_order_value": 1999,
    "daily_usage": [
      {
        "date": "2024-06-20",
        "uses": 12,
        "revenue": 23988
      }
    ]
  }
}