Flow: Seasonal Promotion

Creates event-driven promotional discounts tied to holidays, shopping events, or seasonal milestones. The flow identifies upcoming events based on the site's country and current date, calculates optimal campaign start/end windows, and targets event-relevant product categories with appropriately sized discounts.

Prerequisites

• Wix Stores installed on the site
• Products exist in the catalog
• Access to getCatalogAnalytics, getProductCatalogData, and getSiteData tools
• current_date available for event scheduling
• Site country known for region-specific event mapping

Required APIs

• Create Discount Rule
• Query Discount Rules

Step 1: Identify upcoming event

Use current_date and the site's country (from getSiteData) to identify major holidays or shopping events within the next 30 days.

Common event calendar

If no event is within 30 days, inform the merchant and suggest either a general seasonal promotion or waiting for the next event.

Step 2: Calculate campaign window

Determine the optimal start and end dates for the campaign based on the event date.

Window calculation rules

• Start date: 3-5 days before the event date.
• End date: 1-3 days after the event (or through the following Tuesday for weekend events).
• IMPORTANT: If the calculated start date is before current_date, set start to current_date. Never schedule a campaign to start in the past.

Examples

Combined events

For Black Friday + Cyber Monday, use a single extended window: start the preceding Monday/Tuesday, end the following Tuesday. Do not create two separate discount rules.

Step 3: Gather catalog data

Call getCatalogAnalytics and getProductCatalogData concurrently.

getCatalogAnalytics call:

getProductCatalogData call:

This sort order surfaces the best-selling products first — seasonal campaigns should lead with proven sellers to maximize revenue.

Save the following values:

• total_orders — overall sales volume
• price_p50, price_p90 — price distribution for discount sizing
• avg_profit_margin — sets discount ceiling
• Top products by sales volume

Step 4: Focus on event-relevant categories

Map the identified event to relevant product categories:

If the merchant's catalog matches an event-relevant category, target that category specifically. If no clear match exists, use site-wide scope.

Step 5: Create campaign name

Build a compelling campaign name using the event/period name:

Keep names concise and recognizable. The name is internal (not shown to customers in checkout) but helps merchants manage their promotions.

Step 6: Determine discount scope

• CATEGORY (preferred for event-relevant promotions): Target the event-relevant category with the highest margin and product count.
• SITE (for broad events): Use for events like Black Friday where the expectation is store-wide deals.

Avoid ITEMS scope for seasonal campaigns — seasonal promotions are typically broad rather than targeting individual products.

Step 7: Convert category names to GUIDs (if CATEGORY scope)

If scope is CATEGORY, call getCategoryIds to convert category names to GUIDs.

• Never use category names as scope IDs — always use the GUID.
• Exclude the "All Products" system category.
• Max 3 categoryIds per discount rule.

Step 8: Run guardrail checks

Run the Guardrail: Discount Conflicts checks before creating the rule.

1. Query existing active discount rules:

Endpoint: POST https://www.wixapis.com/ecom/v1/discount-rules/query

Request:

2. Check for time overlap — seasonal promotions have defined windows, so check that no existing rule covers the same period on the same scope.
3. Check for scope overlap — a seasonal category discount stacking with an existing catalog-wide discount could create unexpectedly deep combined discounts.
4. Check for coupon stacking — seasonal events often have high coupon usage.
5. If conflicts found, present to merchant and get confirmation.

Step 9: Create the discount rule with campaign window

Endpoint: POST https://www.wixapis.com/ecom/v1/discount-rules

Request — Black Friday 20% off electronics category, Monday-Tuesday window:

Response:

Request — Valentine's Day site-wide 15% off:

Save the returned id and revision for later management.

Step 10: Verify and remind about deactivation

1. Query discount rules to confirm the new rule exists and is active: true

2. Verify the activeTimeInfo window is correctly set

3. Report to the merchant:

   "{Campaign name} is live: {discount}% off {scope description} from {start_date} to {end_date}. The discount will apply automatically at checkout during this window."

4. IMPORTANT — Deactivation reminder: There is no native auto-deactivation in Wix discount rules. Even though activeTimeInfo.end is set, the rule remains in the system after expiration. Remind the merchant:

   "Note: After {end_date}, the discount will no longer apply at checkout, but the rule will remain active in your dashboard. You may want to deactivate or delete it after the promotion ends to keep your discount rules tidy."

Branching logic

Error Handling

References

• Discount Rules API