PUT
{promotions_service_api_base_url}
/
promotions
/
company
/
{company_id}
/
campaigns
/
{campaign_id}
/
promotions
/
{promotion_id}
{
  "promotion_id": "<string>",
  "campaign_id": "<string>",
  "promotion_name": "<string>",
  "status": "<string>",
  "updates_applied": [
    {}
  ],
  "updates_rejected": [
    {
      "field": "<string>",
      "reason": "<string>",
      "current_value": "<string>"
    }
  ],
  "discount_rules": {},
  "eligibility_criteria": {},
  "usage_limits": {},
  "schedule": {},
  "display_settings": {},
  "performance_impact": {
    "estimated_usage_change": "<string>",
    "revenue_impact_estimate": "<string>",
    "customer_impact_notes": [
      {}
    ]
  },
  "validation_warnings": [
    {}
  ],
  "last_updated": "<string>",
  "updated_by": "<string>",
  "update_history": [
    {
      "timestamp": "<string>",
      "updated_by": "<string>",
      "fields_changed": [
        {}
      ],
      "reason": "<string>"
    }
  ]
}
This endpoint allows modification of existing promotions while maintaining data integrity and ensuring business rules are followed. Different fields have varying update restrictions based on promotion status.
Promotion updates are subject to status-based restrictions. Active promotions have limited modifiable fields to prevent disruption to ongoing customer experiences, while draft promotions can be freely modified.

​
Path Parameters

​
company_id
string
required
The unique identifier of the company that owns the promotion
​
campaign_id
string
required
The unique identifier of the campaign containing the promotion
​
promotion_id
string
required
The unique identifier of the promotion to update

​
Request Body

​
promotion_name
string
Updated display name for the promotion
​
description
string
Updated detailed description of the promotion offer
​
discount_rules
object
Updated discount calculation rules and parameters
​
eligibility_criteria
object
Updated customer and order eligibility requirements
​
usage_limits
object
Updated promotion usage restrictions and limits
​
schedule
object
Updated promotion timing and availability schedule
​
display_settings
object
Updated visual presentation and marketing settings
​
status_action
string
Action to perform on promotion status: “activate”, “pause”, “resume”, “deactivate”
​
auto_apply
boolean
Updated setting for automatic application without requiring a code
​
stackable
boolean
Updated setting for combination with other promotions
​
update_reason
string
Reason for the update (for audit trail)

​
Request Example

{
  "promotion_name": "Spring Fresh 25% Off - Extended",
  "description": "Get 25% off all fresh produce items during our extended Spring Fresh campaign",
  "discount_rules": {
    "discount_value": 25,
    "max_discount_amount": 75.00,
    "min_purchase_amount": 20.00,
    "applicable_categories": ["fresh_produce", "organic_items", "seasonal_items"],
    "excluded_items": ["premium_organics"]
  },
  "usage_limits": {
    "total_usage_limit": 1500,
    "per_customer_limit": 5,
    "daily_usage_limit": 150
  },
  "schedule": {
    "end_date": "2025-05-31T23:59:59.000Z",
    "time_restrictions": {
      "days_of_week": ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday"],
      "hours_of_day": {
        "start": "06:00",
        "end": "22:00"
      }
    }
  },
  "display_settings": {
    "promotional_message": "Save 25% on Fresh Spring Produce - Extended Through May!",
    "banner_text": "SPRING20 - Even More Fresh Savings!",
    "priority_level": 9
  },
  "stackable": true,
  "update_reason": "Extending promotion due to high customer engagement and positive ROI"
}

​
Response

​
promotion_id
string
Unique identifier for the updated promotion
​
campaign_id
string
Parent campaign identifier
​
promotion_name
string
Updated display name of the promotion
​
status
string
Current promotion status after update
​
updates_applied
array
List of fields that were successfully updated
​
updates_rejected
array
List of fields that could not be updated due to restrictions
​
discount_rules
object
Complete updated discount configuration
​
eligibility_criteria
object
Updated customer eligibility requirements
​
usage_limits
object
Updated usage restrictions with current statistics
​
schedule
object
Updated promotion timing and availability
​
display_settings
object
Updated visual presentation configuration
​
performance_impact
object
Estimated impact of changes on promotion performance
​
validation_warnings
array
Non-blocking warnings about the updated configuration
​
last_updated
string
Timestamp of this update
​
updated_by
string
User who performed the update
​
update_history
array
Recent update history for audit purposes

​
Response Example

{
  "promotion_id": "promo_spring_001",
  "campaign_id": "1000010",
  "promotion_name": "Spring Fresh 25% Off - Extended",
  "status": "active",
  "updates_applied": [
    "promotion_name",
    "description",
    "discount_rules.discount_value",
    "discount_rules.max_discount_amount",
    "discount_rules.applicable_categories",
    "usage_limits.total_usage_limit",
    "usage_limits.per_customer_limit",
    "schedule.end_date",
    "schedule.time_restrictions",
    "display_settings.promotional_message",
    "display_settings.banner_text",
    "display_settings.priority_level"
  ],
  "updates_rejected": [
    {
      "field": "discount_rules.min_purchase_amount",
      "reason": "Cannot decrease minimum purchase amount for active promotion with existing usage",
      "current_value": "25.00"
    }
  ],
  "discount_rules": {
    "discount_value": 25,
    "max_discount_amount": 75.00,
    "min_purchase_amount": 25.00,
    "applicable_categories": ["fresh_produce", "organic_items", "seasonal_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": 1500,
    "per_customer_limit": 5,
    "daily_usage_limit": 150,
    "current_usage": {
      "total_used": 247,
      "today_used": 18,
      "remaining_uses": 1253,
      "unique_customers": 189
    }
  },
  "schedule": {
    "start_date": "2025-04-14T00:00:00.000Z",
    "end_date": "2025-05-31T23:59:59.000Z",
    "time_restrictions": {
      "days_of_week": ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday"],
      "hours_of_day": {
        "start": "06:00",
        "end": "22:00"
      }
    }
  },
  "display_settings": {
    "promotional_message": "Save 25% on Fresh Spring Produce - Extended Through May!",
    "banner_text": "SPRING20 - Even More Fresh Savings!",
    "badge_style": "seasonal_green",
    "priority_level": 9
  },
  "performance_impact": {
    "estimated_usage_change": "Increased usage expected due to higher discount and extended availability",
    "revenue_impact_estimate": "Positive impact expected despite higher discount due to extended duration",
    "customer_impact_notes": [
      "Existing customers will see improved offer",
      "Extended weekend availability may increase usage",
      "Higher discount may attract new customer segments"
    ]
  },
  "validation_warnings": [
    "Increasing discount from 20% to 25% will reduce profit margins",
    "Extended end date overlaps with Memorial Day weekend - consider holiday impact"
  ],
  "last_updated": "2025-04-20T15:45:00.000Z",
  "updated_by": "marketing_manager_002",
  "update_history": [
    {
      "timestamp": "2025-04-20T15:45:00.000Z",
      "updated_by": "marketing_manager_002",
      "fields_changed": ["discount_value", "usage_limits", "schedule.end_date"],
      "reason": "Extending promotion due to high customer engagement and positive ROI"
    },
    {
      "timestamp": "2025-04-15T10:30:00.000Z",
      "updated_by": "marketing_admin_001",
      "fields_changed": ["display_settings.banner_text"],
      "reason": "Updated banner text for clarity"
    }
  ]
}
Update Safety: The system prevents updates that could negatively impact customers who have already used the promotion or are in the process of using it.
Performance Optimization: When updating active promotions, monitor performance metrics closely to ensure changes have the desired effect on customer engagement and business objectives.

​
Field Update Rules

​
Status Actions

​
Error Responses

Customer Impact: Updates to active promotions may affect customer experience. Consider the timing of updates and communicate significant changes to customers when appropriate.

​
Best Practices

​
Integration Considerations