> ## 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.

# Update Promotion

> Update an existing promotion's configuration, including discount rules, eligibility criteria, scheduling, and display settings.

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.

<Info>
  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.
</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 update
</ParamField>

### Request Body

<ParamField body="promotion_name" type="string" optional>
  Updated display name for the promotion
</ParamField>

<ParamField body="description" type="string" optional>
  Updated detailed description of the promotion offer
</ParamField>

<ParamField body="discount_rules" type="object" optional>
  Updated discount calculation rules and parameters

  <Expandable title="Discount Rules Updates">
    <ParamField body="discount_value" type="number" optional>
      Updated discount amount (restrictions apply for active promotions)
    </ParamField>

    <ParamField body="max_discount_amount" type="number" optional>
      Updated maximum discount amount for percentage-based discounts
    </ParamField>

    <ParamField body="min_purchase_amount" type="number" optional>
      Updated minimum purchase amount required
    </ParamField>

    <ParamField body="applicable_categories" type="array" optional>
      Updated product categories eligible for the discount
    </ParamField>

    <ParamField body="excluded_items" type="array" optional>
      Updated specific items excluded from the promotion
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="eligibility_criteria" type="object" optional>
  Updated customer and order eligibility requirements

  <Expandable title="Eligibility Updates">
    <ParamField body="customer_segments" type="array" optional>
      Updated customer segments eligible for the promotion
    </ParamField>

    <ParamField body="first_time_customers_only" type="boolean" optional>
      Updated restriction to first-time customers
    </ParamField>

    <ParamField body="loyalty_tier_requirements" type="array" optional>
      Updated required customer loyalty tiers
    </ParamField>

    <ParamField body="geographic_restrictions" type="array" optional>
      Updated geographic regions where promotion is valid
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="usage_limits" type="object" optional>
  Updated promotion usage restrictions and limits

  <Expandable title="Usage Limits Updates">
    <ParamField body="total_usage_limit" type="integer" optional>
      Updated maximum total number of times promotion can be used
    </ParamField>

    <ParamField body="per_customer_limit" type="integer" optional>
      Updated maximum times a single customer can use the promotion
    </ParamField>

    <ParamField body="daily_usage_limit" type="integer" optional>
      Updated maximum daily usage across all customers
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="schedule" type="object" optional>
  Updated promotion timing and availability schedule

  <Expandable title="Schedule Updates">
    <ParamField body="start_date" type="string" optional>
      Updated promotion start date (restrictions apply for active promotions)
    </ParamField>

    <ParamField body="end_date" type="string" optional>
      Updated promotion end date
    </ParamField>

    <ParamField body="time_restrictions" type="object" optional>
      Updated time-based availability restrictions
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="display_settings" type="object" optional>
  Updated visual presentation and marketing settings

  <Expandable title="Display Settings Updates">
    <ParamField body="promotional_message" type="string" optional>
      Updated marketing message displayed to customers
    </ParamField>

    <ParamField body="banner_text" type="string" optional>
      Updated text for promotional banners
    </ParamField>

    <ParamField body="badge_style" type="string" optional>
      Updated visual style for promotion badges
    </ParamField>

    <ParamField body="priority_level" type="integer" optional>
      Updated display priority (1-10, higher shows first)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="status_action" type="string" optional>
  Action to perform on promotion status: "activate", "pause", "resume", "deactivate"
</ParamField>

<ParamField body="auto_apply" type="boolean" optional>
  Updated setting for automatic application without requiring a code
</ParamField>

<ParamField body="stackable" type="boolean" optional>
  Updated setting for combination with other promotions
</ParamField>

<ParamField body="update_reason" type="string" optional>
  Reason for the update (for audit trail)
</ParamField>

### Request Example

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

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

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

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

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

<ResponseField name="updates_applied" type="array">
  List of fields that were successfully updated
</ResponseField>

<ResponseField name="updates_rejected" type="array">
  List of fields that could not be updated due to restrictions

  <Expandable title="Rejected Updates">
    <ResponseField name="field" type="string">Field that was rejected</ResponseField>
    <ResponseField name="reason" type="string">Reason for rejection</ResponseField>
    <ResponseField name="current_value" type="string">Current value that remains unchanged</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="discount_rules" type="object">
  Complete updated discount configuration
</ResponseField>

<ResponseField name="eligibility_criteria" type="object">
  Updated customer eligibility requirements
</ResponseField>

<ResponseField name="usage_limits" type="object">
  Updated usage restrictions with current statistics
</ResponseField>

<ResponseField name="schedule" type="object">
  Updated promotion timing and availability
</ResponseField>

<ResponseField name="display_settings" type="object">
  Updated visual presentation configuration
</ResponseField>

<ResponseField name="performance_impact" type="object">
  Estimated impact of changes on promotion performance

  <Expandable title="Performance Impact">
    <ResponseField name="estimated_usage_change" type="string">Projected change in usage patterns</ResponseField>
    <ResponseField name="revenue_impact_estimate" type="string">Estimated revenue impact of changes</ResponseField>
    <ResponseField name="customer_impact_notes" type="array">Notes about customer experience changes</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="validation_warnings" type="array">
  Non-blocking warnings about the updated configuration
</ResponseField>

<ResponseField name="last_updated" type="string">
  Timestamp of this update
</ResponseField>

<ResponseField name="updated_by" type="string">
  User who performed the update
</ResponseField>

<ResponseField name="update_history" type="array">
  Recent update history for audit purposes

  <Expandable title="Update History">
    <ResponseField name="timestamp" type="string">When the update occurred</ResponseField>
    <ResponseField name="updated_by" type="string">User who made the update</ResponseField>
    <ResponseField name="fields_changed" type="array">List of modified fields</ResponseField>
    <ResponseField name="reason" type="string">Reason for the update</ResponseField>
  </Expandable>
</ResponseField>

### Response Example

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

<Accordion title="Update Restrictions by Status">
  **Draft Status**

  * All fields can be freely modified
  * No restrictions on changes
  * Updates take effect immediately

  **Scheduled Status**

  * Most fields can be updated
  * Start date can be modified if not within 24 hours
  * Promotion code cannot be changed

  **Active Status**

  * Limited field updates allowed
  * Cannot decrease discount value or minimum purchase amounts
  * Cannot restrict eligibility criteria
  * Can extend end date and increase usage limits
  * Display settings can be updated

  **Paused Status**

  * Same restrictions as active status
  * Can modify status to resume or deactivate
  * Schedule modifications allowed

  **Expired/Completed Status**

  * No modifications allowed except for display settings
  * Updates primarily for archival and reporting purposes
  * Cannot reactivate expired promotions
</Accordion>

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

<Tip>
  **Performance Optimization**: When updating active promotions, monitor performance metrics closely to ensure changes have the desired effect on customer engagement and business objectives.
</Tip>

### Field Update Rules

<Accordion title="Detailed Update Validation Rules">
  **Discount Rules**

  * Cannot decrease discount percentage for active promotions
  * Cannot decrease maximum discount amount if customers have used higher amounts
  * Cannot increase minimum purchase amount for active promotions
  * Adding categories is allowed, removing requires validation

  **Usage Limits**

  * Can increase limits at any time
  * Cannot decrease below current usage levels
  * Per-customer limits cannot exceed total limits
  * Daily limits adjust automatically if needed

  **Schedule Changes**

  * Cannot move start date to the past
  * Can extend end date for any status except expired
  * Time restrictions can be expanded but not reduced for active promotions
  * Timezone changes require special validation

  **Eligibility Criteria**

  * Cannot make criteria more restrictive for active promotions
  * Can expand customer segments and geographic regions
  * Loyalty tier requirements can be relaxed but not tightened
  * New restrictions apply only to future usage
</Accordion>

### Status Actions

<Accordion title="Available Status Actions">
  **Activate**

  * Move from draft or scheduled to active
  * Requires valid configuration and future or current start date
  * Begins tracking performance metrics

  **Pause**

  * Temporarily disable active promotion
  * Preserves configuration and usage statistics
  * Can be resumed later

  **Resume**

  * Reactivate a paused promotion
  * Continues from where it left off
  * No configuration reset required

  **Deactivate**

  * Permanently disable promotion before natural expiration
  * Cannot be reactivated
  * Preserves all historical data
</Accordion>

### Error Responses

<Accordion title="Common Update Error Scenarios">
  **Invalid Update for Status**

  ```json theme={null}
  {
    "error": "Invalid update for promotion status",
    "message": "Cannot decrease discount value for active promotion",
    "code": "INVALID_UPDATE_FOR_STATUS",
    "current_status": "active",
    "rejected_field": "discount_rules.discount_value"
  }
  ```

  **Validation Failure**

  ```json theme={null}
  {
    "error": "Validation failed",
    "message": "End date must be after start date",
    "code": "VALIDATION_FAILED",
    "field": "schedule.end_date"
  }
  ```

  **Usage Limit Conflict**

  ```json theme={null}
  {
    "error": "Usage limit conflict",
    "message": "Cannot set total usage limit below current usage count",
    "code": "USAGE_LIMIT_CONFLICT",
    "current_usage": 247,
    "requested_limit": 200
  }
  ```

  **Promotion Not Found**

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

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

### Best Practices

<Accordion title="Update Best Practices">
  **Planning Updates**

  * Review current usage patterns before making changes
  * Consider customer impact of modifications
  * Test changes in staging environment when possible
  * Document reasons for updates for audit trail

  **Active Promotion Updates**

  * Prefer extending rather than restricting benefits
  * Update display settings for immediate customer visibility
  * Monitor performance impact after changes
  * Communicate significant changes to customer service team

  **Performance Monitoring**

  * Track metrics before and after updates
  * Set up alerts for unexpected usage pattern changes
  * Review customer feedback for update impact
  * Adjust based on real-world performance data

  **Compliance and Audit**

  * Maintain detailed update logs
  * Include business justification for changes
  * Follow approval processes for significant modifications
  * Ensure regulatory compliance for promotional changes
</Accordion>

### Integration Considerations

<Accordion title="System Integration Impact">
  **Frontend Applications**

  * Updated display settings reflect immediately
  * Cache invalidation may be required
  * Mobile app synchronization timing
  * Real-time notification systems

  **Analytics Systems**

  * Performance metric recalculation
  * Historical data integrity maintenance
  * Reporting dashboard updates
  * Trend analysis adjustments

  **Customer Communications**

  * Email marketing system updates
  * Push notification content changes
  * Website banner modifications
  * Social media content coordination

  **Business Operations**

  * Inventory planning adjustments
  * Staff training on promotion changes
  * Customer service preparation
  * Financial impact assessment
</Accordion>