Create Promotion

This endpoint creates promotional offers within campaigns, enabling businesses to offer discounts, special deals, and incentives to drive customer engagement and sales.

Promotions are campaign-specific marketing tools that provide customers with discounts, special offers, or incentives. Each promotion operates within the context of a parent campaign.

Path Parameters

company_id

string

required

The unique identifier of the company creating the promotion

campaign_id

string

required

The unique identifier of the campaign that will contain this promotion

Request Body

promotion_name

string

required

Display name for the promotion (e.g., “Spring Sale 20% Off”)

promotion_type

string

required

Type of promotion: “percentage_discount”, “fixed_amount_discount”, “buy_x_get_y”, “free_shipping”, “bundle_deal”, “loyalty_bonus”

description

string

required

Detailed description of the promotion offer

promotion_code

string

Unique promotional code customers can use (auto-generated if not provided)

discount_rules

object

required

Discount calculation rules and parameters

Show Discount Rules Object

discount_value

number

required

The discount amount (percentage for percentage_discount, fixed amount for fixed_amount_discount)

max_discount_amount

number

Maximum discount amount for percentage-based discounts

min_purchase_amount

number

Minimum purchase amount required to apply the discount

applicable_categories

array

Product categories eligible for the discount

excluded_items

array

Specific items excluded from the promotion

eligibility_criteria

object

Customer and order eligibility requirements

Show Eligibility Criteria

customer_segments

array

Customer segments eligible for the promotion

first_time_customers_only

boolean

default:"false"

Restrict promotion to first-time customers

loyalty_tier_requirements

array

Required customer loyalty tiers

geographic_restrictions

array

Geographic regions where promotion is valid

usage_limits

object

Promotion usage restrictions and limits

Show Usage Limits

total_usage_limit

integer

Maximum total number of times promotion can be used

per_customer_limit

integer

Maximum times a single customer can use the promotion

daily_usage_limit

integer

Maximum daily usage across all customers

schedule

object

required

Promotion timing and availability schedule

Show Schedule Object

start_date

string

required

When the promotion becomes active (ISO 8601 format)

end_date

string

required

When the promotion expires (ISO 8601 format)

time_restrictions

object

Time-based availability restrictions

display_settings

object

Visual presentation and marketing settings

Show Display Settings

promotional_message

string

Marketing message displayed to customers

banner_text

string

Text for promotional banners

badge_style

string

Visual style for promotion badges

priority_level

integer

default:"5"

Display priority (1-10, higher shows first)

auto_apply

boolean

default:"false"

Whether to automatically apply the promotion without requiring a code

stackable

boolean

default:"false"

Whether this promotion can be combined with other promotions

Request Example

{
  "promotion_name": "Spring Fresh 20% Off",
  "promotion_type": "percentage_discount",
  "description": "Get 20% off all fresh produce items during our Spring Fresh campaign",
  "promotion_code": "SPRING20",
  "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
  },
  "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"
      }
    }
  },
  "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
  },
  "auto_apply": false,
  "stackable": true
}

Response

promotion_id

string

Unique identifier for the created promotion

campaign_id

string

Parent campaign identifier

promotion_name

string

Display name of the promotion

promotion_type

string

Type of promotion created

promotion_code

string

Promotional code (generated if not provided)

status

string

Current promotion status (“draft”, “scheduled”, “active”, “paused”, “expired”)

discount_rules

object

Complete discount configuration as created

eligibility_criteria

object

Customer eligibility requirements

usage_limits

object

Usage restrictions and current usage statistics

schedule

object

Promotion timing and availability

display_settings

object

Visual presentation configuration

performance_metrics

object

Initial promotion tracking metrics

Show Performance Metrics

total_uses

integer

Current usage count

unique_customers

integer

Number of unique customers who used promotion

total_discount_given

number

Total discount amount provided

conversion_rate

number

Promotion conversion rate

created_at

string

Timestamp when the promotion was created

created_by

string

User who created 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",
  "status": "scheduled",
  "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": 0,
      "today_used": 0,
      "remaining_uses": 1000
    }
  },
  "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"
      }
    }
  },
  "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
  },
  "auto_apply": false,
  "stackable": true,
  "performance_metrics": {
    "total_uses": 0,
    "unique_customers": 0,
    "total_discount_given": 0.00,
    "conversion_rate": 0.00
  },
  "created_at": "2025-04-14T01:00:00.000Z",
  "created_by": "marketing_admin_001"
}

Promotion Types and Strategies

Promotion Codes: If no promotion code is provided, the system will auto-generate a unique code based on the promotion name and type. Custom codes must be unique within the company.

Performance Optimization: Set appropriate usage limits to control promotion costs while maximizing customer engagement. Monitor performance metrics to optimize future promotions.

Validation Rules

Promotion Validation Requirements

Error Responses

Common Error Scenarios

Invalid Discount Configuration

{
  "error": "Invalid discount rules",
  "message": "Discount percentage cannot exceed 100%",
  "code": "INVALID_DISCOUNT_RULES"
}

Duplicate Promotion Code

{
  "error": "Promotion code already exists",
  "message": "The promotion code 'SPRING20' is already in use",
  "code": "DUPLICATE_PROMOTION_CODE"
}

Invalid Schedule

{
  "error": "Invalid promotion schedule",
  "message": "End date must be after start date",
  "code": "INVALID_SCHEDULE"
}

Campaign Not Found

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

Budget Considerations: Carefully configure usage limits and maximum discount amounts to control promotional costs. Monitor usage patterns to prevent budget overruns.

Best Practices

Promotion Creation Best Practices

API Documentation - Legacy

API Documentation - Latest

Path Parameters

Request Body

Request Example

Response

Response Example

Validation Rules

Error Responses

Best Practices

API Documentation - Legacy

API Documentation - Latest

​Path Parameters

​Request Body

​Request Example

​Response

​Response Example

​Validation Rules

​Error Responses

​Best Practices

Path Parameters

Request Body

Request Example

Response

Response Example

Validation Rules

Error Responses

Best Practices