Skip to main content
GET
{promotions_service_api_base_url}
/
promotions
/
company
/
{company_id}
/
campaigns
/
{campaign_id}
/
promotions
/
{promotion_id}
{
  "promotion_id": "<string>",
  "campaign_id": "<string>",
  "promotion_name": "<string>",
  "promotion_type": "<string>",
  "promotion_code": "<string>",
  "description": "<string>",
  "status": "<string>",
  "discount_rules": {
    "discount_value": 123,
    "max_discount_amount": 123,
    "min_purchase_amount": 123,
    "applicable_categories": [
      {}
    ],
    "excluded_items": [
      {}
    ]
  },
  "eligibility_criteria": {
    "customer_segments": [
      {}
    ],
    "first_time_customers_only": true,
    "loyalty_tier_requirements": [
      {}
    ],
    "geographic_restrictions": [
      {}
    ]
  },
  "usage_limits": {
    "total_usage_limit": 123,
    "per_customer_limit": 123,
    "daily_usage_limit": 123,
    "current_usage": {}
  },
  "schedule": {
    "start_date": "<string>",
    "end_date": "<string>",
    "time_restrictions": {},
    "timezone": "<string>"
  },
  "display_settings": {
    "promotional_message": "<string>",
    "banner_text": "<string>",
    "badge_style": "<string>",
    "priority_level": 123
  },
  "performance_metrics": {
    "total_uses": 123,
    "unique_customers": 123,
    "total_discount_given": 123,
    "total_revenue_impact": 123,
    "conversion_rate": 123,
    "average_order_value": 123,
    "repeat_usage_rate": 123
  },
  "usage_history": [
    {
      "date": "<string>",
      "daily_uses": 123,
      "daily_revenue": 123,
      "daily_discount": 123
    }
  ],
  "customer_segment_analysis": {
    "segment_performance": [
      {}
    ],
    "top_performing_segments": [
      {}
    ],
    "geographic_distribution": {}
  },
  "auto_apply": true,
  "stackable": true,
  "created_at": "<string>",
  "created_by": "<string>",
  "last_updated": "<string>",
  "updated_by": "<string>"
}
This endpoint provides complete information about a specific promotion within a campaign, including real-time performance data, customer usage patterns, and detailed configuration settings.
This endpoint returns comprehensive promotion data including current performance metrics, which is essential for monitoring promotion effectiveness and making data-driven optimization decisions.

​
Path Parameters

​
company_id
string
required
The unique identifier of the company that owns the promotion
​
campaign_id
string
required
The unique identifier of the campaign containing the promotion
​
promotion_id
string
required
The unique identifier of the promotion to retrieve

​
Query Parameters

​
include_metrics
boolean
default:"true"
Include detailed performance metrics in the response
​
include_usage_history
boolean
default:"false"
Include historical usage data and trends
​
metrics_period
string
default:"all"
Time period for metrics: “today”, “week”, “month”, “all”
​
include_customer_segments
boolean
default:"false"
Include customer segment analysis data

​
Response

​
promotion_id
string
Unique identifier for the promotion
​
campaign_id
string
Parent campaign identifier
​
promotion_name
string
Display name of the promotion
​
promotion_type
string
Type of promotion (percentage_discount, fixed_amount_discount, etc.)
​
promotion_code
string
Promotional code customers use to redeem
​
description
string
Detailed description of the promotion
​
status
string
Current promotion status (draft, scheduled, active, paused, expired, completed)
​
discount_rules
object
Complete discount configuration and rules
​
eligibility_criteria
object
Customer and order eligibility requirements
​
usage_limits
object
Promotion usage restrictions and current statistics
​
schedule
object
Promotion timing and availability schedule
​
display_settings
object
Visual presentation and marketing settings
​
performance_metrics
object
Comprehensive promotion performance data
​
usage_history
array
Historical usage data and trends (if requested)
​
customer_segment_analysis
object
Customer segment performance analysis (if requested)
​
auto_apply
boolean
Whether promotion is automatically applied
​
stackable
boolean
Whether promotion can be combined with others
​
created_at
string
Timestamp when promotion was created
​
created_by
string
User who created the promotion
​
last_updated
string
Timestamp of last modification
​
updated_by
string
User who last modified the promotion

​
Response Example

{
  "promotion_id": "promo_spring_001",
  "campaign_id": "1000010",
  "promotion_name": "Spring Fresh 20% Off",
  "promotion_type": "percentage_discount",
  "promotion_code": "SPRING20",
  "description": "Get 20% off all fresh produce items during our Spring Fresh campaign",
  "status": "active",
  "discount_rules": {
    "discount_value": 20,
    "max_discount_amount": 50.00,
    "min_purchase_amount": 25.00,
    "applicable_categories": ["fresh_produce", "organic_items"],
    "excluded_items": ["premium_organics"]
  },
  "eligibility_criteria": {
    "customer_segments": ["regular_customers", "premium_members"],
    "first_time_customers_only": false,
    "loyalty_tier_requirements": ["bronze", "silver", "gold"],
    "geographic_restrictions": ["northeast_region"]
  },
  "usage_limits": {
    "total_usage_limit": 1000,
    "per_customer_limit": 3,
    "daily_usage_limit": 100,
    "current_usage": {
      "total_used": 247,
      "today_used": 18,
      "remaining_uses": 753,
      "unique_customers": 189,
      "usage_percentage": 24.7
    }
  },
  "schedule": {
    "start_date": "2025-04-14T00:00:00.000Z",
    "end_date": "2025-05-14T23:59:59.000Z",
    "time_restrictions": {
      "days_of_week": ["monday", "tuesday", "wednesday", "thursday", "friday"],
      "hours_of_day": {
        "start": "08:00",
        "end": "20:00"
      }
    },
    "timezone": "America/New_York"
  },
  "display_settings": {
    "promotional_message": "Save 20% on Fresh Spring Produce!",
    "banner_text": "SPRING20 - Fresh Savings All Month Long",
    "badge_style": "seasonal_green",
    "priority_level": 8
  },
  "performance_metrics": {
    "total_uses": 247,
    "unique_customers": 189,
    "total_discount_given": 3247.85,
    "total_revenue_impact": 18450.32,
    "conversion_rate": 15.8,
    "average_order_value": 74.72,
    "repeat_usage_rate": 23.3,
    "roi": 468.2
  },
  "usage_history": [
    {
      "date": "2025-04-14",
      "daily_uses": 23,
      "daily_revenue": 1654.50,
      "daily_discount": 208.90
    },
    {
      "date": "2025-04-15",
      "daily_uses": 31,
      "daily_revenue": 2187.30,
      "daily_discount": 287.45
    }
  ],
  "customer_segment_analysis": {
    "segment_performance": [
      {
        "segment": "regular_customers",
        "usage_count": 156,
        "conversion_rate": 14.2,
        "average_order_value": 68.45
      },
      {
        "segment": "premium_members",
        "usage_count": 91,
        "conversion_rate": 18.7,
        "average_order_value": 85.32
      }
    ],
    "top_performing_segments": ["premium_members", "regular_customers"],
    "geographic_distribution": {
      "northeast_region": {
        "usage_count": 247,
        "conversion_rate": 15.8,
        "revenue_impact": 18450.32
      }
    }
  },
  "auto_apply": false,
  "stackable": true,
  "created_at": "2025-04-14T01:00:00.000Z",
  "created_by": "marketing_admin_001",
  "last_updated": "2025-04-20T14:30:00.000Z",
  "updated_by": "marketing_manager_002"
}
Usage Metrics
  • Total Uses: Number of times the promotion code was successfully applied
  • Unique Customers: Count of individual customers who used the promotion
  • Repeat Usage Rate: Percentage of customers who used the promotion multiple times
Financial Metrics
  • Total Discount Given: Sum of all discount amounts provided
  • Revenue Impact: Total revenue generated from orders using the promotion
  • ROI: Return on investment calculated as (Revenue - Discount) / Discount
Conversion Metrics
  • Conversion Rate: Percentage of promotion exposures that resulted in usage
  • Average Order Value: Mean order amount for promotion users
  • Usage Percentage: Percentage of total usage limit consumed
Real-Time Data: Performance metrics are updated in real-time, providing current usage statistics and performance indicators for active promotions.
Optimization Insights: Use customer segment analysis and usage history to identify the most effective promotion strategies and optimize future campaigns.

​
Status Definitions

Draft
  • Promotion is created but not yet scheduled
  • Can be freely edited and modified
  • Not visible to customers
Scheduled
  • Promotion is configured and waiting for start date
  • Limited editing capabilities
  • Not yet active for customers
Active
  • Promotion is currently running and available
  • Customers can use the promotion code
  • Performance metrics are being tracked
Paused
  • Temporarily disabled by administrator
  • Can be reactivated without losing configuration
  • Not available to customers during pause
Expired
  • Promotion has passed its end date
  • No longer available for new usage
  • Historical data remains accessible
Completed
  • Promotion reached its usage limit before expiration
  • No longer available for new usage
  • All limits have been exhausted

​
Error Responses

Promotion Not Found
{
  "error": "Promotion not found",
  "message": "The specified promotion does not exist",
  "code": "PROMOTION_NOT_FOUND"
}
Campaign Mismatch
{
  "error": "Campaign mismatch",
  "message": "The promotion does not belong to the specified campaign",
  "code": "CAMPAIGN_MISMATCH"
}
Access Denied
{
  "error": "Access denied",
  "message": "You do not have permission to view this promotion",
  "code": "ACCESS_DENIED"
}
Invalid Metrics Period
{
  "error": "Invalid metrics period",
  "message": "Metrics period must be one of: today, week, month, all",
  "code": "INVALID_METRICS_PERIOD"
}
Performance Impact: Including usage history and customer segment analysis significantly increases response size. Use these options judiciously based on actual needs.

​
Data Analysis Use Cases

Performance Monitoring
  • Track real-time promotion effectiveness
  • Monitor usage patterns and trends
  • Identify peak usage periods
Customer Behavior Analysis
  • Understand which customer segments respond best
  • Analyze repeat usage patterns
  • Identify geographic performance variations
Financial Impact Assessment
  • Calculate true ROI of promotional campaigns
  • Understand cost vs. revenue relationship
  • Optimize discount levels for maximum impact
Strategic Planning
  • Use historical data for future promotion planning
  • Identify successful promotion characteristics
  • Optimize timing and targeting strategies

​
Integration with Analytics

Business Intelligence Systems
  • Export promotion performance data
  • Integrate with existing BI dashboards
  • Create custom analytics reports
Marketing Automation
  • Trigger follow-up campaigns based on usage
  • Segment customers based on promotion behavior
  • Automate promotion optimization
Inventory Management
  • Track promotion impact on inventory movement
  • Adjust stock levels based on promotion performance
  • Plan inventory for future promotional periods
Customer Relationship Management
  • Update customer profiles with promotion usage
  • Create targeted segments for future campaigns
  • Track customer lifetime value impact
⌘I