GET
{promotions_service_api_base_url}
/
promotions
/
company
/
{company_id}
/
campaigns
/
{campaign_id}
/
promotions
{
  "campaign_id": "<string>",
  "campaign_name": "<string>",
  "total_promotions": 123,
  "pagination": {
    "current_page": 123,
    "total_pages": 123,
    "per_page": 123,
    "total_items": 123,
    "has_next": true,
    "has_previous": true
  },
  "filters_applied": {},
  "promotions": [
    {
      "promotion_id": "<string>",
      "promotion_name": "<string>",
      "promotion_type": "<string>",
      "promotion_code": "<string>",
      "status": "<string>",
      "description": "<string>",
      "discount_summary": {
        "discount_value": 123,
        "discount_type": "<string>",
        "max_discount": 123,
        "min_purchase": 123
      },
      "schedule": {
        "start_date": "<string>",
        "end_date": "<string>",
        "duration_days": 123,
        "time_remaining": "<string>"
      },
      "performance_metrics": {
        "total_uses": 123,
        "unique_customers": 123,
        "conversion_rate": 123,
        "total_discount_given": 123,
        "revenue_impact": 123,
        "roi": 123,
        "performance_rating": "<string>"
      },
      "usage_limits": {
        "total_limit": 123,
        "current_usage": 123,
        "remaining_uses": 123,
        "usage_percentage": 123
      },
      "created_at": "<string>",
      "created_by": "<string>",
      "last_updated": "<string>"
    }
  ],
  "summary_statistics": {
    "status_breakdown": {},
    "type_breakdown": {},
    "performance_summary": {},
    "usage_summary": {},
    "financial_summary": {}
  }
}
This endpoint provides access to all promotions within a specific campaign, offering powerful filtering and sorting options to help businesses manage their promotional strategies effectively.
This endpoint supports extensive filtering and pagination capabilities, making it ideal for promotion management dashboards, analytics reporting, and bulk operations across multiple promotions.

​
Path Parameters

​
company_id
string
required
The unique identifier of the company that owns the promotions
​
campaign_id
string
required
The unique identifier of the campaign containing the promotions

​
Query Parameters

​
status
string
Filter by promotion status: “all”, “draft”, “scheduled”, “active”, “paused”, “expired”, “completed”
​
promotion_type
string
Filter by promotion type: “percentage_discount”, “fixed_amount_discount”, “buy_x_get_y”, “free_shipping”, “bundle_deal”, “loyalty_bonus”
​
created_after
string
Filter promotions created after this date (ISO 8601 format)
​
created_before
string
Filter promotions created before this date (ISO 8601 format)
​
start_date_after
string
Filter promotions starting after this date
​
end_date_before
string
Filter promotions ending before this date
​
performance_threshold
string
Filter by performance level: “high_performing”, “moderate”, “low_performing”, “no_usage”
​
discount_range
string
Filter by discount range: “0-10”, “10-25”, “25-50”, “50+”
​
customer_segment
string
Filter promotions available to specific customer segment
​
search
string
Search in promotion names, descriptions, and codes
​
sort_by
string
default:"created_at"
Sort field: “created_at”, “name”, “status”, “performance”, “usage_count”, “start_date”, “end_date”
​
sort_order
string
default:"desc"
Sort direction: “asc” or “desc”
​
page
integer
default:"1"
Page number for pagination
​
limit
integer
default:"25"
Number of promotions per page (max 100)
​
include_metrics
boolean
default:"true"
Include performance metrics in the response
​
include_archived
boolean
default:"false"
Include archived/deleted promotions in results
​
summary_stats
boolean
default:"true"
Include summary statistics for the filtered set

​
Response

​
campaign_id
string
The campaign identifier
​
campaign_name
string
Name of the parent campaign
​
total_promotions
integer
Total number of promotions matching filters
​
pagination
object
Pagination information for the results
​
filters_applied
object
Summary of filters applied to the query
​
promotions
array
Array of promotion objects matching the search criteria
​
summary_statistics
object
Aggregate statistics for the filtered promotion set

​
Response Example

{
  "campaign_id": "1000010",
  "campaign_name": "Spring Fresh Campaign",
  "total_promotions": 8,
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "per_page": 25,
    "total_items": 8,
    "has_next": false,
    "has_previous": false
  },
  "filters_applied": {
    "status": "all",
    "include_metrics": true,
    "sort_by": "created_at",
    "sort_order": "desc"
  },
  "promotions": [
    {
      "promotion_id": "promo_spring_001",
      "promotion_name": "Spring Fresh 20% Off",
      "promotion_type": "percentage_discount",
      "promotion_code": "SPRING20",
      "status": "active",
      "description": "Get 20% off all fresh produce items",
      "discount_summary": {
        "discount_value": 20,
        "discount_type": "percentage",
        "max_discount": 50.00,
        "min_purchase": 25.00
      },
      "schedule": {
        "start_date": "2025-04-14T00:00:00.000Z",
        "end_date": "2025-05-14T23:59:59.000Z",
        "duration_days": 30,
        "time_remaining": "18 days"
      },
      "performance_metrics": {
        "total_uses": 247,
        "unique_customers": 189,
        "conversion_rate": 15.8,
        "total_discount_given": 3247.85,
        "revenue_impact": 18450.32,
        "roi": 468.2,
        "performance_rating": "high_performing"
      },
      "usage_limits": {
        "total_limit": 1000,
        "current_usage": 247,
        "remaining_uses": 753,
        "usage_percentage": 24.7
      },
      "created_at": "2025-04-14T01:00:00.000Z",
      "created_by": "marketing_admin_001",
      "last_updated": "2025-04-20T14:30:00.000Z"
    },
    {
      "promotion_id": "promo_spring_002",
      "promotion_name": "Buy 2 Get 1 Free Organics",
      "promotion_type": "buy_x_get_y",
      "promotion_code": "ORGANIC3",
      "status": "active",
      "description": "Buy 2 organic items, get 1 free",
      "discount_summary": {
        "discount_value": 33.33,
        "discount_type": "buy_x_get_y",
        "max_discount": null,
        "min_purchase": 0.00
      },
      "schedule": {
        "start_date": "2025-04-15T00:00:00.000Z",
        "end_date": "2025-04-30T23:59:59.000Z",
        "duration_days": 15,
        "time_remaining": "3 days"
      },
      "performance_metrics": {
        "total_uses": 89,
        "unique_customers": 76,
        "conversion_rate": 12.4,
        "total_discount_given": 1247.32,
        "revenue_impact": 5680.45,
        "roi": 355.5,
        "performance_rating": "moderate"
      },
      "usage_limits": {
        "total_limit": 500,
        "current_usage": 89,
        "remaining_uses": 411,
        "usage_percentage": 17.8
      },
      "created_at": "2025-04-15T09:00:00.000Z",
      "created_by": "marketing_admin_001",
      "last_updated": "2025-04-15T09:00:00.000Z"
    }
  ],
  "summary_statistics": {
    "status_breakdown": {
      "active": 5,
      "scheduled": 2,
      "draft": 1,
      "paused": 0,
      "expired": 0,
      "completed": 0
    },
    "type_breakdown": {
      "percentage_discount": 4,
      "buy_x_get_y": 2,
      "fixed_amount_discount": 1,
      "free_shipping": 1
    },
    "performance_summary": {
      "total_uses_across_all": 542,
      "total_unique_customers": 387,
      "average_conversion_rate": 14.2,
      "total_discount_given": 7845.67,
      "total_revenue_impact": 34567.89,
      "average_roi": 440.6
    },
    "usage_summary": {
      "total_usage_capacity": 3500,
      "total_current_usage": 542,
      "average_usage_percentage": 18.5,
      "promotions_near_limit": 0
    },
    "financial_summary": {
      "total_revenue_generated": 34567.89,
      "total_discounts_provided": 7845.67,
      "net_revenue_impact": 26722.22,
      "average_order_value_with_promotions": 73.45
    }
  }
}
Performance Ratings: Promotions are automatically rated based on conversion rates, ROI, and usage patterns compared to campaign averages and historical benchmarks.
Bulk Operations: Use filtering to identify groups of promotions for bulk operations like status changes, performance analysis, or strategic planning.

​
Search Capabilities

​
Sorting and Organization

​
Error Responses

Large Result Sets: When querying campaigns with many promotions, use pagination and filtering to maintain good performance. The system may timeout on very large unfiltered requests.

​
Use Cases and Applications

​
Integration with Analytics