Get All Promotions

Get All Promotions

curl --request GET \
  --url 'https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions'

import requests

url = "https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions"

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', 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",
  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"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions")

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

{
  "campaign_id": "<string>",
  "campaign_name": "<string>",
  "total_promotions": 123,
  "pagination": {
    "current_page": 123,
    "total_pages": 123,
    "per_page": 123,
    "total_items": 123,
    "has_next": true,
    "has_previous": true
  },
  "filters_applied": {},
  "promotions": [
    {
      "promotion_id": "<string>",
      "promotion_name": "<string>",
      "promotion_type": "<string>",
      "promotion_code": "<string>",
      "status": "<string>",
      "description": "<string>",
      "discount_summary": {
        "discount_value": 123,
        "discount_type": "<string>",
        "max_discount": 123,
        "min_purchase": 123
      },
      "schedule": {
        "start_date": "<string>",
        "end_date": "<string>",
        "duration_days": 123,
        "time_remaining": "<string>"
      },
      "performance_metrics": {
        "total_uses": 123,
        "unique_customers": 123,
        "conversion_rate": 123,
        "total_discount_given": 123,
        "revenue_impact": 123,
        "roi": 123,
        "performance_rating": "<string>"
      },
      "usage_limits": {
        "total_limit": 123,
        "current_usage": 123,
        "remaining_uses": 123,
        "usage_percentage": 123
      },
      "created_at": "<string>",
      "created_by": "<string>",
      "last_updated": "<string>"
    }
  ],
  "summary_statistics": {
    "status_breakdown": {},
    "type_breakdown": {},
    "performance_summary": {},
    "usage_summary": {},
    "financial_summary": {}
  }
}

GET

{promotions_service_api_base_url}

promotions

company

{company_id}

campaigns

{campaign_id}

promotions

Get All Promotions

curl --request GET \
  --url 'https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions'

import requests

url = "https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions"

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', 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",
  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"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/{{promotions_service_api_base_url}}/promotions/company/{{company_id}}/campaigns/{{campaign_id}}/promotions")

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

{
  "campaign_id": "<string>",
  "campaign_name": "<string>",
  "total_promotions": 123,
  "pagination": {
    "current_page": 123,
    "total_pages": 123,
    "per_page": 123,
    "total_items": 123,
    "has_next": true,
    "has_previous": true
  },
  "filters_applied": {},
  "promotions": [
    {
      "promotion_id": "<string>",
      "promotion_name": "<string>",
      "promotion_type": "<string>",
      "promotion_code": "<string>",
      "status": "<string>",
      "description": "<string>",
      "discount_summary": {
        "discount_value": 123,
        "discount_type": "<string>",
        "max_discount": 123,
        "min_purchase": 123
      },
      "schedule": {
        "start_date": "<string>",
        "end_date": "<string>",
        "duration_days": 123,
        "time_remaining": "<string>"
      },
      "performance_metrics": {
        "total_uses": 123,
        "unique_customers": 123,
        "conversion_rate": 123,
        "total_discount_given": 123,
        "revenue_impact": 123,
        "roi": 123,
        "performance_rating": "<string>"
      },
      "usage_limits": {
        "total_limit": 123,
        "current_usage": 123,
        "remaining_uses": 123,
        "usage_percentage": 123
      },
      "created_at": "<string>",
      "created_by": "<string>",
      "last_updated": "<string>"
    }
  ],
  "summary_statistics": {
    "status_breakdown": {},
    "type_breakdown": {},
    "performance_summary": {},
    "usage_summary": {},
    "financial_summary": {}
  }
}

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.

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

Path Parameters

string

required

The unique identifier of the company that owns the promotions

string

required

The unique identifier of the campaign containing the promotions

Query Parameters

string

Filter by promotion status: “all”, “draft”, “scheduled”, “active”, “paused”, “expired”, “completed”

string

Filter by promotion type: “percentage_discount”, “fixed_amount_discount”, “buy_x_get_y”, “free_shipping”, “bundle_deal”, “loyalty_bonus”

string

Filter promotions created after this date (ISO 8601 format)

string

Filter promotions created before this date (ISO 8601 format)

string

Filter promotions starting after this date

string

Filter promotions ending before this date

string

Filter by performance level: “high_performing”, “moderate”, “low_performing”, “no_usage”

string

Filter by discount range: “0-10”, “10-25”, “25-50”, “50+”

string

Filter promotions available to specific customer segment

string

Search in promotion names, descriptions, and codes

string

default:"created_at"

Sort field: “created_at”, “name”, “status”, “performance”, “usage_count”, “start_date”, “end_date”

string

default:"desc"

Sort direction: “asc” or “desc”

integer

default:"1"

Page number for pagination

integer

default:"25"

Number of promotions per page (max 100)

boolean

default:"true"

Include performance metrics in the response

boolean

default:"false"

Include archived/deleted promotions in results

boolean

default:"true"

Include summary statistics for the filtered set

Response

string

The campaign identifier

string

Name of the parent campaign

integer

Total number of promotions matching filters

object

Pagination information for the results

Show Pagination Details

integer

Current page number

integer

Total number of pages

integer

Items per page

integer

Total items across all pages

boolean

Whether there are more pages

boolean

Whether there are previous pages

object

Summary of filters applied to the query

array

Array of promotion objects matching the search criteria

Show Promotion Object

string

Unique identifier for the promotion

string

Display name of the promotion

string

Type of promotion

string

Promotional code for customer use

string

Current promotion status

string

Brief description of the promotion

object

Summary of discount configuration

Show Discount Summary

number

Primary discount amount/percentage

string

Type of discount applied

number

Maximum discount amount

number

Minimum purchase requirement

object

Promotion timing information

Show Schedule Summary

string

Promotion start date

string

Promotion end date

integer

Total promotion duration

string

Time remaining until expiration

object

Key performance indicators (if requested)

Show Performance Metrics

integer

Total number of promotion uses

integer

Number of unique customers

number

Promotion conversion rate

number

Total discount amount provided

number

Total revenue generated

number

Return on investment

string

Overall performance rating

object

Current usage status and limits

Show Usage Status

integer

Maximum total uses allowed

integer

Current number of uses

integer

Remaining uses available

number

Percentage of limit used

string

When the promotion was created

string

User who created the promotion

string

When the promotion was last modified

object

Aggregate statistics for the filtered promotion set

Show Summary Statistics

object

Count of promotions by status

object

Count of promotions by type

object

Aggregate performance metrics

object

Overall usage statistics

object

Financial impact summary

Response Example

{
  "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
    }
  }
}

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

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

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

Search Capabilities

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

Sorting and Organization

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

Error Responses

Common Query Error Scenarios

Invalid Filter Parameters

{
  "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

{
  "error": "Invalid date range",
  "message": "created_after date must be before created_before date",
  "code": "INVALID_DATE_RANGE"
}

Pagination Errors

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

Campaign Not Found

{
  "error": "Campaign not found",
  "message": "The specified campaign does not exist or is not accessible",
  "code": "CAMPAIGN_NOT_FOUND"
}

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.

Use Cases and Applications

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

Integration with Analytics

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

API Documentation - Legacy

API Documentation - Latest

Path Parameters

Query Parameters

Response

Response Example

Search Capabilities

Sorting and Organization

Error Responses

Use Cases and Applications

Integration with Analytics

​Path Parameters

​Query Parameters

​Response

​Response Example

​Search Capabilities

​Sorting and Organization

​Error Responses

​Use Cases and Applications

​Integration with Analytics

Path Parameters

Query Parameters

Response

Response Example

Search Capabilities

Sorting and Organization

Error Responses

Use Cases and Applications

Integration with Analytics