> ## 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 All Promotions

> Retrieve a comprehensive list of all promotions within a campaign, with advanced filtering, sorting, and analytics capabilities.

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.

<Info>
  This endpoint supports extensive filtering and pagination capabilities, making it ideal for promotion management dashboards, analytics reporting, and bulk operations across multiple promotions.
</Info>

### Path Parameters

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

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

### Query Parameters

<ParamField query="status" type="string" optional>
  Filter by promotion status: "all", "draft", "scheduled", "active", "paused", "expired", "completed"
</ParamField>

<ParamField query="promotion_type" type="string" optional>
  Filter by promotion type: "percentage\_discount", "fixed\_amount\_discount", "buy\_x\_get\_y", "free\_shipping", "bundle\_deal", "loyalty\_bonus"
</ParamField>

<ParamField query="created_after" type="string" optional>
  Filter promotions created after this date (ISO 8601 format)
</ParamField>

<ParamField query="created_before" type="string" optional>
  Filter promotions created before this date (ISO 8601 format)
</ParamField>

<ParamField query="start_date_after" type="string" optional>
  Filter promotions starting after this date
</ParamField>

<ParamField query="end_date_before" type="string" optional>
  Filter promotions ending before this date
</ParamField>

<ParamField query="performance_threshold" type="string" optional>
  Filter by performance level: "high\_performing", "moderate", "low\_performing", "no\_usage"
</ParamField>

<ParamField query="discount_range" type="string" optional>
  Filter by discount range: "0-10", "10-25", "25-50", "50+"
</ParamField>

<ParamField query="customer_segment" type="string" optional>
  Filter promotions available to specific customer segment
</ParamField>

<ParamField query="search" type="string" optional>
  Search in promotion names, descriptions, and codes
</ParamField>

<ParamField query="sort_by" type="string" optional default="created_at">
  Sort field: "created\_at", "name", "status", "performance", "usage\_count", "start\_date", "end\_date"
</ParamField>

<ParamField query="sort_order" type="string" optional default="desc">
  Sort direction: "asc" or "desc"
</ParamField>

<ParamField query="page" type="integer" optional default="1">
  Page number for pagination
</ParamField>

<ParamField query="limit" type="integer" optional default="25">
  Number of promotions per page (max 100)
</ParamField>

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

<ParamField query="include_archived" type="boolean" optional default="false">
  Include archived/deleted promotions in results
</ParamField>

<ParamField query="summary_stats" type="boolean" optional default="true">
  Include summary statistics for the filtered set
</ParamField>

### Response

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

<ResponseField name="campaign_name" type="string">
  Name of the parent campaign
</ResponseField>

<ResponseField name="total_promotions" type="integer">
  Total number of promotions matching filters
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination information for the results

  <Expandable title="Pagination Details">
    <ResponseField name="current_page" type="integer">Current page number</ResponseField>
    <ResponseField name="total_pages" type="integer">Total number of pages</ResponseField>
    <ResponseField name="per_page" type="integer">Items per page</ResponseField>
    <ResponseField name="total_items" type="integer">Total items across all pages</ResponseField>
    <ResponseField name="has_next" type="boolean">Whether there are more pages</ResponseField>
    <ResponseField name="has_previous" type="boolean">Whether there are previous pages</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="filters_applied" type="object">
  Summary of filters applied to the query
</ResponseField>

<ResponseField name="promotions" type="array">
  Array of promotion objects matching the search criteria

  <Expandable title="Promotion Object">
    <ResponseField name="promotion_id" type="string">
      Unique identifier for the promotion
    </ResponseField>

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

    <ResponseField name="promotion_type" type="string">
      Type of promotion
    </ResponseField>

    <ResponseField name="promotion_code" type="string">
      Promotional code for customer use
    </ResponseField>

    <ResponseField name="status" type="string">
      Current promotion status
    </ResponseField>

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

    <ResponseField name="discount_summary" type="object">
      Summary of discount configuration

      <Expandable title="Discount Summary">
        <ResponseField name="discount_value" type="number">Primary discount amount/percentage</ResponseField>
        <ResponseField name="discount_type" type="string">Type of discount applied</ResponseField>
        <ResponseField name="max_discount" type="number">Maximum discount amount</ResponseField>
        <ResponseField name="min_purchase" type="number">Minimum purchase requirement</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="schedule" type="object">
      Promotion timing information

      <Expandable title="Schedule Summary">
        <ResponseField name="start_date" type="string">Promotion start date</ResponseField>
        <ResponseField name="end_date" type="string">Promotion end date</ResponseField>
        <ResponseField name="duration_days" type="integer">Total promotion duration</ResponseField>
        <ResponseField name="time_remaining" type="string">Time remaining until expiration</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="performance_metrics" type="object">
      Key performance indicators (if requested)

      <Expandable title="Performance Metrics">
        <ResponseField name="total_uses" type="integer">Total number of promotion uses</ResponseField>
        <ResponseField name="unique_customers" type="integer">Number of unique customers</ResponseField>
        <ResponseField name="conversion_rate" type="number">Promotion conversion rate</ResponseField>
        <ResponseField name="total_discount_given" type="number">Total discount amount provided</ResponseField>
        <ResponseField name="revenue_impact" type="number">Total revenue generated</ResponseField>
        <ResponseField name="roi" type="number">Return on investment</ResponseField>
        <ResponseField name="performance_rating" type="string">Overall performance rating</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="usage_limits" type="object">
      Current usage status and limits

      <Expandable title="Usage Status">
        <ResponseField name="total_limit" type="integer">Maximum total uses allowed</ResponseField>
        <ResponseField name="current_usage" type="integer">Current number of uses</ResponseField>
        <ResponseField name="remaining_uses" type="integer">Remaining uses available</ResponseField>
        <ResponseField name="usage_percentage" type="number">Percentage of limit used</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the promotion was created
    </ResponseField>

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

    <ResponseField name="last_updated" type="string">
      When the promotion was last modified
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="summary_statistics" type="object">
  Aggregate statistics for the filtered promotion set

  <Expandable title="Summary Statistics">
    <ResponseField name="status_breakdown" type="object">
      Count of promotions by status
    </ResponseField>

    <ResponseField name="type_breakdown" type="object">
      Count of promotions by type
    </ResponseField>

    <ResponseField name="performance_summary" type="object">
      Aggregate performance metrics
    </ResponseField>

    <ResponseField name="usage_summary" type="object">
      Overall usage statistics
    </ResponseField>

    <ResponseField name="financial_summary" type="object">
      Financial impact summary
    </ResponseField>
  </Expandable>
</ResponseField>

### Response Example

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

<Accordion title="Advanced Filtering Options">
  **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
</Accordion>

<Note>
  **Performance Ratings**: Promotions are automatically rated based on conversion rates, ROI, and usage patterns compared to campaign averages and historical benchmarks.
</Note>

<Tip>
  **Bulk Operations**: Use filtering to identify groups of promotions for bulk operations like status changes, performance analysis, or strategic planning.
</Tip>

### Search Capabilities

<Accordion title="Search and Discovery Features">
  **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
</Accordion>

### Sorting and Organization

<Accordion title="Data Organization Options">
  **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
</Accordion>

### Error Responses

<Accordion title="Common Query Error Scenarios">
  **Invalid Filter Parameters**

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

  ```json theme={null}
  {
    "error": "Invalid date range",
    "message": "created_after date must be before created_before date",
    "code": "INVALID_DATE_RANGE"
  }
  ```

  **Pagination Errors**

  ```json theme={null}
  {
    "error": "Invalid pagination",
    "message": "Page number must be positive and limit cannot exceed 100",
    "code": "INVALID_PAGINATION",
    "max_limit": 100
  }
  ```

  **Campaign Not Found**

  ```json theme={null}
  {
    "error": "Campaign not found",
    "message": "The specified campaign does not exist or is not accessible",
    "code": "CAMPAIGN_NOT_FOUND"
  }
  ```
</Accordion>

<Warning>
  **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.
</Warning>

### Use Cases and Applications

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

### Integration with Analytics

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