Skip to main content
GET
Get Promotion Details
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

string
required
The unique identifier of the company that owns the promotion
string
required
The unique identifier of the campaign containing the promotion
string
required
The unique identifier of the promotion to retrieve

Query Parameters

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

Response

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

Response Example

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
Campaign Mismatch
Access Denied
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