Skip to main content
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
    }
  }
}
Status-Based Filtering
  • Filter by current promotion lifecycle stage
  • Identify promotions requiring attention
  • Separate active campaigns from drafts and archives
  • Track promotion performance by status
Performance-Based Filtering
  • High-performing: Above average conversion and ROI
  • Moderate: Meeting baseline performance metrics
  • Low-performing: Below threshold performance
  • No usage: Promotions with zero customer engagement
Date Range Filtering
  • Creation date ranges for administrative tracking
  • Active date ranges for operational planning
  • Expiration tracking for renewal planning
  • Seasonal promotion identification
Customer Segment Filtering
  • Target-specific customer group promotions
  • Loyalty tier-based promotion management
  • Geographic region-specific campaigns
  • Demographic-targeted promotion analysis
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

Text Search
  • Search across promotion names for quick identification
  • Full-text search in promotion descriptions
  • Promotional code pattern matching
  • Creator and modifier user search
Advanced Query Syntax
  • Combine multiple filters for precise results
  • Use wildcards in text searches
  • Date range combinations
  • Performance threshold combinations
Saved Searches
  • Create frequently-used filter combinations
  • Share search configurations across team members
  • Set up alerts for specific promotion criteria
  • Automate reporting based on saved filters
Smart Suggestions
  • System suggests relevant filters based on search patterns
  • Recommendation of similar promotions
  • Identification of optimization opportunities
  • Performance benchmark comparisons

​
Sorting and Organization

Performance-Based Sorting
  • Sort by conversion rate for effectiveness analysis
  • Order by ROI for financial impact review
  • Arrange by usage count for popularity assessment
  • Organize by revenue impact for business value
Temporal Sorting
  • Chronological creation order for administrative tracking
  • Start date sorting for campaign planning
  • End date sorting for renewal management
  • Last modified sorting for recent changes
Alphabetical Organization
  • Name-based sorting for easy browsing
  • Code-based organization for systematic review
  • Creator-based grouping for team management
  • Status-based clustering for workflow optimization
Custom Sort Combinations
  • Multi-field sorting for complex organization
  • Priority-based arrangement for urgent actions
  • Performance-time combinations for trend analysis
  • Status-performance matrices for strategic review

​
Error Responses

Invalid Filter Parameters
{
  "error": "Invalid filter parameter",
  "message": "Invalid promotion_type: 'invalid_type'",
  "code": "INVALID_FILTER_VALUE",
  "valid_values": ["percentage_discount", "fixed_amount_discount", "buy_x_get_y", "free_shipping", "bundle_deal", "loyalty_bonus"]
}
Date Range Errors
{
  "error": "Invalid date range",
  "message": "created_after date must be before created_before date",
  "code": "INVALID_DATE_RANGE"
}
Pagination Errors
{
  "error": "Invalid pagination",
  "message": "Page number must be positive and limit cannot exceed 100",
  "code": "INVALID_PAGINATION",
  "max_limit": 100
}
Campaign Not Found
{
  "error": "Campaign not found",
  "message": "The specified campaign does not exist or is not accessible",
  "code": "CAMPAIGN_NOT_FOUND"
}
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

Campaign Management
  • Monitor all promotions within a campaign
  • Identify underperforming promotions for optimization
  • Track campaign-wide promotional success
  • Plan promotion renewal and extension strategies
Performance Analysis
  • Compare promotion effectiveness across types
  • Identify best-performing promotional strategies
  • Analyze customer response patterns
  • Benchmark promotion performance against goals
Operational Management
  • Track promotion usage and capacity planning
  • Identify promotions requiring urgent attention
  • Manage promotion lifecycle and renewals
  • Coordinate marketing team efforts
Strategic Planning
  • Analyze historical promotion performance
  • Identify successful promotion patterns
  • Plan future promotional strategies
  • Optimize promotion portfolio composition
Financial Reporting
  • Calculate total promotional impact on revenue
  • Assess discount costs across all promotions
  • Analyze ROI for promotional investments
  • Support budget planning and allocation

​
Integration with Analytics

Dashboard Integration
  • Real-time promotion performance dashboards
  • Campaign-level promotional analytics
  • Customer engagement tracking
  • Financial impact visualization
Export Capabilities
  • CSV export for offline analysis
  • Integration with business intelligence tools
  • Custom report generation
  • Automated reporting schedules
API Integration
  • Webhook notifications for promotion events
  • Real-time data feeds for external systems
  • Integration with marketing automation platforms
  • Custom analytics solution connectivity
Data Warehouse Integration
  • Historical data archiving
  • Long-term trend analysis
  • Cross-campaign comparison analytics
  • Predictive modeling support
⌘I