Get Promotion Details
curl --request GET \
--url 'https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions/{{promotion_id}}'import requests
url = "https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions/{{promotion_id}}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions/{{promotion_id}}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions/{{promotion_id}}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions/{{promotion_id}}"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions/{{promotion_id}}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions/{{promotion_id}}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"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>"
}Promotions
Get Promotion Details
Retrieve comprehensive details for a specific promotion, including performance metrics, usage statistics, and configuration settings.
GET
{promotions_service_api_base_url}
/
promotions
/
company
/
{company_id}
/
campaigns
/
{campaign_id}
/
promotions
/
{promotion_id}
Get Promotion Details
curl --request GET \
--url 'https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions/{{promotion_id}}'import requests
url = "https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions/{{promotion_id}}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions/{{promotion_id}}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions/{{promotion_id}}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions/{{promotion_id}}"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions/{{promotion_id}}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions/{{promotion_id}}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"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
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
object
object
object
object
object
Comprehensive promotion performance data
Show Performance Metrics
Show Performance Metrics
integer
Total number of times promotion was used
integer
Number of unique customers who used promotion
number
Total discount amount provided to customers
number
Total revenue generated from promotion usage
number
Percentage of promotion views that converted to usage
number
Average order value for promotion users
number
Percentage of customers who used promotion multiple times
array
object
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
{
"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"
}
Performance Metrics Explained
Performance Metrics Explained
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
- 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 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
Promotion Status Explained
Promotion Status Explained
Draft
- Promotion is created but not yet scheduled
- Can be freely edited and modified
- Not visible to customers
- Promotion is configured and waiting for start date
- Limited editing capabilities
- Not yet active for customers
- Promotion is currently running and available
- Customers can use the promotion code
- Performance metrics are being tracked
- Temporarily disabled by administrator
- Can be reactivated without losing configuration
- Not available to customers during pause
- Promotion has passed its end date
- No longer available for new usage
- Historical data remains accessible
- Promotion reached its usage limit before expiration
- No longer available for new usage
- All limits have been exhausted
Error Responses
Common Error Scenarios
Common Error Scenarios
Promotion Not FoundCampaign MismatchAccess DeniedInvalid Metrics Period
{
"error": "Promotion not found",
"message": "The specified promotion does not exist",
"code": "PROMOTION_NOT_FOUND"
}
{
"error": "Campaign mismatch",
"message": "The promotion does not belong to the specified campaign",
"code": "CAMPAIGN_MISMATCH"
}
{
"error": "Access denied",
"message": "You do not have permission to view this promotion",
"code": "ACCESS_DENIED"
}
{
"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
Analytics and Optimization
Analytics and Optimization
Performance Monitoring
- Track real-time promotion effectiveness
- Monitor usage patterns and trends
- Identify peak usage periods
- Understand which customer segments respond best
- Analyze repeat usage patterns
- Identify geographic performance variations
- Calculate true ROI of promotional campaigns
- Understand cost vs. revenue relationship
- Optimize discount levels for maximum impact
- Use historical data for future promotion planning
- Identify successful promotion characteristics
- Optimize timing and targeting strategies
Integration with Analytics
Analytics Integration Points
Analytics Integration Points
Business Intelligence Systems
- Export promotion performance data
- Integrate with existing BI dashboards
- Create custom analytics reports
- Trigger follow-up campaigns based on usage
- Segment customers based on promotion behavior
- Automate promotion optimization
- Track promotion impact on inventory movement
- Adjust stock levels based on promotion performance
- Plan inventory for future promotional periods
- Update customer profiles with promotion usage
- Create targeted segments for future campaigns
- Track customer lifetime value impact

