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

• Products exist in the catalog (siteData.hasCatalog === true, checked at context load)
• current_date available for event scheduling
• Site country known for region-specific event mapping (siteData.country, loaded by eCommerce Load Context)

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: Use pre-loaded catalog data

Catalog analytics and product data are already in conversation context — do NOT re-fetch:

• siteData.catalogAnalytics — category groups with sum(ordersCount), quantiles([0.5,0.9], price), avg(profitMargin). Loaded by the eCommerce Load Context.
• siteData.productCatalogData — per-product list sorted ordersCount DESC for SEASONAL goal. Loaded by the run-a-sale orchestrator Step 5.

Extract from context:

• total_orders — sum(ordersCount) from the "All Products" group in siteData.catalogAnalytics
• price_p50, price_p90 — from quantiles in siteData.catalogAnalytics
• avg_profit_margin — sets discount ceiling
• Top products by sales volume — from siteData.productCatalogData

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 pre-create guardrails in Create Discount Rule → "Guardrails" before creating the rule. For seasonal campaigns the most relevant are time overlap (defined windows — ensure no existing rule covers the same period/scope), scope overlap (a category discount stacking with a catalog-wide one), and coupon stacking (seasonal events drive high coupon usage). Present any conflicts to the 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