Scheduled Promotions Manager

Paid pluginsize Mplanned, not built

Indicative price, not an offer: €20–30/month (€240–360/year)

Generated from docs/plan/paid/scheduled-promotions-manager/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A paid module that adds calendar UI for managing time-based promotions (flash sales, seasonal discounts, holiday campaigns). Merchants view a calendar, drag-to-schedule promotions (e.g., ‘Black Friday 50% off’, Sep 20–22), and see upcoming events. The system integrates with cart-price-rules and price-history to apply rules automatically at scheduled times.

The problem

Creating multiple time-based promotions via API or raw cron expressions is tedious. Merchants want a calendar UI: ‘click Sep 20, add Black Friday sale, set dates, done’. Without a visual interface, merchants either miss scheduling windows or overspend on support calls to set up campaigns.

What it does

• Calendar view: month/year selector, shows scheduled promotions as colored blocks on dates
• Create promotion: click date range → form opens (name, discount type/amount, products affected, apply free shipping?)
• Manage promotion: edit start/end times, discount amounts, pause/resume before start
• Bulk promotion template: merchant can duplicate a past promotion (‘use Black Friday 2023 template’) and adjust dates/discount
• Notification reminders: email alert 3 days before promotion starts, 1 day before, and reminder that it’s live
• Campaign analytics: show promotion performance (# orders, revenue, discount amount, profitability)
• Conflict detection: if two promotions overlap on same product, warn merchant (‘both apply, highest discount wins’)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Email campaign scheduling (future marketing module owns this; this is promotion scheduling only)
• Complex rule conditions (e.g., ‘discount only if customer has no VIP tier’); use cart-price-rules for conditions
• AI-optimized discount suggestions (paid advanced analytics module owns this)

Data model

No new tables; builds on cart_price_rules (adds UI). Scheduled promotions are just cart_price_rules with start_date/end_date set. Add promotion_campaign table: { id, shop_id, campaign_name, rules_ids (array of cart_price_rules), template_of (for duplicating), performance (JSON: {orders, revenue, discount_total})}.

API

• POST /admin/promotion-campaigns — create campaign with rules and dates
• GET /admin/promotion-campaigns — list campaigns with calendar view data
• PUT /admin/promotion-campaigns/:id — edit campaign
• GET /admin/promotion-campaigns/:id/performance — analytics for campaign

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Add ‘Promotion Calendar’ in Commerce > Promotions. Calendar view (month): shows scheduled campaigns as colored blocks. Click date range to create campaign. Form: campaign name, rules (new or copy from template), start/end dates and times. Show ‘Performance’ tab: # orders, AOV, total discount amount, profitability. Duplicate button: ‘Use as template for next campaign’.

The seam — why this is paid

Paid module owns the calendar UI and campaign management experience. Core cart-price-rules own the rule evaluation logic. Merchants without this module manage promotions via API or raw cart-price-rules (less convenient).

Admin UX premium, not required for function (rules work via API). Justifies paid as time-saver for high-volume campaign merchants.

Dependencies

• cart-price-rules (promotions are implemented as cart rules)
• Scheduler/cron (to activate/deactivate rules at scheduled times)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Merchant clicks date range Sep 20–22, creates ‘Black Friday’, sets 50% off all products
• Calendar shows ‘Black Friday 50% off’ block on Sep 20–22
• At Sep 20 00:00 UTC, cart-price-rules for this campaign auto-activate; at Sep 23 00:00, auto-deactivate
• Performance tab shows ‘Black Friday: 500 orders, €25k revenue, €5k discount, €20k profit’
• Merchant duplicates Black Friday 2024 template, adjusts dates to next Sep 20–22, changes discount to 40%

Risks

If promotion auto-activation time is server timezone instead of shop timezone, campaign runs at wrong time (always convert to shop timezone before scheduling). If performance metrics are not updated in real-time, dashboard shows stale data (async job to calculate performance nightly is acceptable).

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.