> ## Documentation Index
> Fetch the complete documentation index at: https://developer.lulacommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Promotion Details

> Retrieve comprehensive details for a specific promotion, including performance metrics, usage statistics, and configuration settings.

This endpoint provides complete information about a specific promotion within a campaign, including real-time performance data, customer usage patterns, and detailed configuration settings.

<Info>
  This endpoint returns comprehensive promotion data including current performance metrics, which is essential for monitoring promotion effectiveness and making data-driven optimization decisions.
</Info>

### Path Parameters

<ParamField path="company_id" type="string" required>
  The unique identifier of the company that owns the promotion
</ParamField>

<ParamField path="campaign_id" type="string" required>
  The unique identifier of the campaign containing the promotion
</ParamField>

<ParamField path="promotion_id" type="string" required>
  The unique identifier of the promotion to retrieve
</ParamField>

### Query Parameters

<ParamField query="include_metrics" type="boolean" optional default="true">
  Include detailed performance metrics in the response
</ParamField>

<ParamField query="include_usage_history" type="boolean" optional default="false">
  Include historical usage data and trends
</ParamField>

<ParamField query="metrics_period" type="string" optional default="all">
  Time period for metrics: "today", "week", "month", "all"
</ParamField>

<ParamField query="include_customer_segments" type="boolean" optional default="false">
  Include customer segment analysis data
</ParamField>

### Response

<ResponseField name="promotion_id" type="string">
  Unique identifier for the promotion
</ResponseField>

<ResponseField name="campaign_id" type="string">
  Parent campaign identifier
</ResponseField>

<ResponseField name="promotion_name" type="string">
  Display name of the promotion
</ResponseField>

<ResponseField name="promotion_type" type="string">
  Type of promotion (percentage\_discount, fixed\_amount\_discount, etc.)
</ResponseField>

<ResponseField name="promotion_code" type="string">
  Promotional code customers use to redeem
</ResponseField>

<ResponseField name="description" type="string">
  Detailed description of the promotion
</ResponseField>

<ResponseField name="status" type="string">
  Current promotion status (draft, scheduled, active, paused, expired, completed)
</ResponseField>

<ResponseField name="discount_rules" type="object">
  Complete discount configuration and rules

  <Expandable title="Discount Rules">
    <ResponseField name="discount_value" type="number">
      The discount amount or percentage
    </ResponseField>

    <ResponseField name="max_discount_amount" type="number">
      Maximum discount amount for percentage-based discounts
    </ResponseField>

    <ResponseField name="min_purchase_amount" type="number">
      Minimum purchase amount required
    </ResponseField>

    <ResponseField name="applicable_categories" type="array">
      Product categories eligible for the discount
    </ResponseField>

    <ResponseField name="excluded_items" type="array">
      Specific items excluded from the promotion
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="eligibility_criteria" type="object">
  Customer and order eligibility requirements

  <Expandable title="Eligibility Criteria">
    <ResponseField name="customer_segments" type="array">
      Customer segments eligible for the promotion
    </ResponseField>

    <ResponseField name="first_time_customers_only" type="boolean">
      Whether restricted to first-time customers
    </ResponseField>

    <ResponseField name="loyalty_tier_requirements" type="array">
      Required customer loyalty tiers
    </ResponseField>

    <ResponseField name="geographic_restrictions" type="array">
      Geographic regions where promotion is valid
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage_limits" type="object">
  Promotion usage restrictions and current statistics

  <Expandable title="Usage Limits and Stats">
    <ResponseField name="total_usage_limit" type="integer">
      Maximum total number of uses allowed
    </ResponseField>

    <ResponseField name="per_customer_limit" type="integer">
      Maximum uses per individual customer
    </ResponseField>

    <ResponseField name="daily_usage_limit" type="integer">
      Maximum daily usage across all customers
    </ResponseField>

    <ResponseField name="current_usage" type="object">
      Real-time usage statistics
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="schedule" type="object">
  Promotion timing and availability schedule

  <Expandable title="Schedule Details">
    <ResponseField name="start_date" type="string">
      When the promotion becomes active
    </ResponseField>

    <ResponseField name="end_date" type="string">
      When the promotion expires
    </ResponseField>

    <ResponseField name="time_restrictions" type="object">
      Time-based availability restrictions
    </ResponseField>

    <ResponseField name="timezone" type="string">
      Timezone for schedule interpretation
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="display_settings" type="object">
  Visual presentation and marketing settings

  <Expandable title="Display Configuration">
    <ResponseField name="promotional_message" type="string">
      Marketing message displayed to customers
    </ResponseField>

    <ResponseField name="banner_text" type="string">
      Text for promotional banners
    </ResponseField>

    <ResponseField name="badge_style" type="string">
      Visual style for promotion badges
    </ResponseField>

    <ResponseField name="priority_level" type="integer">
      Display priority level
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="performance_metrics" type="object">
  Comprehensive promotion performance data

  <Expandable title="Performance Metrics">
    <ResponseField name="total_uses" type="integer">
      Total number of times promotion was used
    </ResponseField>

    <ResponseField name="unique_customers" type="integer">
      Number of unique customers who used promotion
    </ResponseField>

    <ResponseField name="total_discount_given" type="number">
      Total discount amount provided to customers
    </ResponseField>

    <ResponseField name="total_revenue_impact" type="number">
      Total revenue generated from promotion usage
    </ResponseField>

    <ResponseField name="conversion_rate" type="number">
      Percentage of promotion views that converted to usage
    </ResponseField>

    <ResponseField name="average_order_value" type="number">
      Average order value for promotion users
    </ResponseField>

    <ResponseField name="repeat_usage_rate" type="number">
      Percentage of customers who used promotion multiple times
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage_history" type="array" required={false}>
  Historical usage data and trends (if requested)

  <Expandable title="Usage History">
    <ResponseField name="date" type="string">
      Date of usage data point
    </ResponseField>

    <ResponseField name="daily_uses" type="integer">
      Number of uses on this date
    </ResponseField>

    <ResponseField name="daily_revenue" type="number">
      Revenue generated on this date
    </ResponseField>

    <ResponseField name="daily_discount" type="number">
      Total discount given on this date
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="customer_segment_analysis" type="object" required={false}>
  Customer segment performance analysis (if requested)

  <Expandable title="Segment Analysis">
    <ResponseField name="segment_performance" type="array">
      Performance metrics broken down by customer segment
    </ResponseField>

    <ResponseField name="top_performing_segments" type="array">
      Customer segments with highest engagement
    </ResponseField>

    <ResponseField name="geographic_distribution" type="object">
      Usage distribution across geographic regions
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="auto_apply" type="boolean">
  Whether promotion is automatically applied
</ResponseField>

<ResponseField name="stackable" type="boolean">
  Whether promotion can be combined with others
</ResponseField>

<ResponseField name="created_at" type="string">
  Timestamp when promotion was created
</ResponseField>

<ResponseField name="created_by" type="string">
  User who created the promotion
</ResponseField>

<ResponseField name="last_updated" type="string">
  Timestamp of last modification
</ResponseField>

<ResponseField name="updated_by" type="string">
  User who last modified the promotion
</ResponseField>

### Response Example

```json theme={null}
{
  "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"
}
```

<Accordion title="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

  **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
</Accordion>

<Note>
  **Real-Time Data**: Performance metrics are updated in real-time, providing current usage statistics and performance indicators for active promotions.
</Note>

<Tip>
  **Optimization Insights**: Use customer segment analysis and usage history to identify the most effective promotion strategies and optimize future campaigns.
</Tip>

### Status Definitions

<Accordion title="Promotion Status Explained">
  **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
</Accordion>

### Error Responses

<Accordion title="Common Error Scenarios">
  **Promotion Not Found**

  ```json theme={null}
  {
    "error": "Promotion not found",
    "message": "The specified promotion does not exist",
    "code": "PROMOTION_NOT_FOUND"
  }
  ```

  **Campaign Mismatch**

  ```json theme={null}
  {
    "error": "Campaign mismatch",
    "message": "The promotion does not belong to the specified campaign",
    "code": "CAMPAIGN_MISMATCH"
  }
  ```

  **Access Denied**

  ```json theme={null}
  {
    "error": "Access denied",
    "message": "You do not have permission to view this promotion",
    "code": "ACCESS_DENIED"
  }
  ```

  **Invalid Metrics Period**

  ```json theme={null}
  {
    "error": "Invalid metrics period",
    "message": "Metrics period must be one of: today, week, month, all",
    "code": "INVALID_METRICS_PERIOD"
  }
  ```
</Accordion>

<Warning>
  **Performance Impact**: Including usage history and customer segment analysis significantly increases response size. Use these options judiciously based on actual needs.
</Warning>

### Data Analysis Use Cases

<Accordion title="Analytics and Optimization">
  **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
</Accordion>

### Integration with Analytics

<Accordion title="Analytics Integration Points">
  **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
</Accordion>