Promo Scheduler for Magento 2: User Guide

Plan your promotions ahead and let Magento switch them on and off to the minute. A typical Black Friday on 27 November could look like this:

Each line is a campaign: a time window (once, every day or every week) with one or more cart and catalog price rules. You see all campaigns on one calendar, get warnings when campaigns overlap, copy campaigns to new dates, save sets of campaigns as templates and compare the results of up to four campaigns.

• Changelog: Release notes · Questions: FAQ

1. Requirements

The module works in the admin only. Shoppers see the effect of your rules (lower prices, discounts, free shipping) exactly as with rules you switch on by hand. On Adobe Commerce with Content Staging the module switches the rule version that is current at that moment; do not schedule the same rule with Content Staging as well.

2. Installation

With Composer, using the Composer keys from your account on commercegears.com (see https://commercegears.com/composer-access/):

composer config repositories.commercegears composer https://repo.commercegears.com
composer config --auth http-basic.repo.commercegears.com PUBLIC_KEY PRIVATE_KEY
composer require commercegears/module-promo-scheduler
bin/magento setup:upgrade
bin/magento setup:di:compile            # production mode only
bin/magento setup:static-content:deploy # production mode only
bin/magento cache:flush

The scheduler runs from Magento cron in its own cron group commercegears_promo_scheduler, every minute and in its own process, so long jobs of other modules do not delay your campaigns. Check that the server crontab runs bin/magento cron:run every minute.

3. Quick start (5 minutes)

1. Go to CommerceGears > Promotions > Campaign Calendar and click Add Campaign (or click a free slot in the week or day view: the start time is filled in for you).
2. Enter a Name, for example "Black Friday: 30% off clothing", and optionally a Group such as "Black Friday 2026".
3. Under Schedule set the start date and time and the end date and time (24-hour clock, store time zone).
4. Under Promotions choose existing Catalog Price Rules and/or Cart Price Rules, or open Create a New Rule to create one here.
5. Save Campaign. The messages tell you whether the campaign started at once, whether its rules were switched off until the start, and whether the checks found an overlap.

4. Campaigns

4.1 Schedule

• Times are in the time zone of the default scope (Stores > Configuration > General > General > Locale Options > Timezone). The campaign form shows it, with the current time there.
• The end time is not included: a window from 06:00 to 12:00 stops at 12:00. For a window until midnight, use 00:00 of the next day (or 23:59 if you prefer).
• Repeat: Does not repeat, Every day or Every week on chosen days. A repeating campaign keeps the start and end time of its first window, also across daylight saving changes ("every Friday 18:00 to 21:00" stays 18:00 local time in winter and summer). Repeat Until is the last date on which a window may start; leave it empty to repeat without an end. A daily window can last up to 24 hours, a weekly one up to 7 days.

4.2 Promotions (rules)

A campaign controls the Active switch of its rules while it is enabled: on at the start of each window, off at the end.

• Leave the rules' own From and To dates empty. Magento only knows whole days there; the scheduler takes care of the exact times. The checks warn when a rule's dates exclude a window.
• When you save an enabled campaign that has not started yet, its rules are switched off until the start (setting Switch Off Rules Until the Campaign Starts). Rules that another running campaign uses are left on.
• A rule can belong to several campaigns. It is switched off only when no running campaign uses it any more.
• If you switch a rule on or off by hand between two windows, the module leaves it as it is until the next window starts.
• Cart rules with a coupon still need their coupon code during the window.
• Disabling or deleting a running campaign stops it at once and switches its rules off. Deleting a campaign never deletes rules.

4.3 Create a New Rule

Open Create a New Rule in the campaign form and switch on Create a Rule With This Campaign:

The rule is created inactive and linked to the campaign. For more conditions, open it later in Marketing > Cart Price Rules or Marketing > Catalog Price Rules.

4.4 Storefront

Storefront Label and Landing Page URL are optional. When you install other CommerceGears promotion modules (for example a countdown bar or a cart progress bar), they can show campaigns that have a storefront label, such as "Black Friday: 30% off clothing, ends in 02:14:33". Campaigns without a label stay private.

4.5 The campaign page

Below the form you find:

• Checks: overlaps and time zone traps for this campaign (see section 6).
• Next Windows: the next five windows.
• Linked Rules: each rule with its discount and whether it is active now, with a link to the rule.
• Switch Log: planned and actual switch times, delay, number of rules and products switched, and who switched (cron, admin or CLI).
• Change History: who changed the campaign and what changed.

5. Calendar

CommerceGears > Promotions > Campaign Calendar shows all campaigns:

• Month, Week, Day and List views. The list view is a timeline grouped by day with times, groups, rules and status.
• Colours show the type: catalog price rules, cart price rules, both, or no rules. Disabled campaigns are hatched, finished ones faded, running ones outlined. A round "!" marks campaigns with warnings; hover a campaign to see its rules and warnings.
• Move: in the week and day views, drag a campaign that has not started yet to another time or day (15-minute steps). Drag the lower edge to change the end. In the month view, drag a campaign to another day. Moving a repeating campaign moves the whole series (you are asked first).
• Plan: click a free slot in the week or day view to open a new campaign at that time.
• Checks for this period lists every warning for the visible dates.

6. Checks

The module warns about:

Products are compared by the categories and SKUs in the rules' conditions. Rules with other conditions (for example price or colour) are reported as "may apply to the same products".

7. Copies and templates

• Copy to New Dates: in Scheduled Campaigns select campaigns and choose Copy to New Dates (or use the button on a campaign page). Pick the new date of the first campaign; the others keep their distance in days and their times of day. Choose whether the rules are copied (new inactive rules you can change without touching the old campaign; recommended) or shared. Copied rules have no From/To dates, because the campaign decides when they run. Cart rules with one fixed coupon code are always shared because coupon codes must be unique. You can give the copies a new group.
• Templates: select campaigns and choose Save as Template, for example "Black Friday weekend". In CommerceGears > Promotions > Campaign Templates click Use Template, choose the first day, a group and how to handle the rules. The campaigns are created and the calendar opens on that date.

8. Results

CommerceGears > Promotions > Campaign Results compares up to four campaigns side by side (also from the Results button of a campaign):

• Campaign orders: orders placed during the windows that used one of the campaign's cart rules, or that contain a product its catalog rules covered while it ran; their revenue, the discount given, units sold and average order value.
• Store totals: all orders, revenue, units and average order value during the windows, compared with a window of the same length directly before each one, with the change in percent.

Cancelled orders are left out and refunds (credit memos) are deducted. Amounts are in the base currency. Export CSV downloads the table.

9. Settings

Stores > Configuration > CommerceGears > Scheduled Promotions (default scope):

10. Command line

bin/magento commercegears:promo:scheduler:run [--dry-run]      # start and stop what is due now
bin/magento commercegears:promo:scheduler:status [--json]      # last run, delay, running and next campaigns, recent switches, warnings (30 days)
bin/magento commercegears:promo:scheduler:results 12 13        # results of campaigns 12 and 13 as JSON

11. Permissions (ACL)

Under CommerceGears > Promotions > Scheduled Promotions:

12. Troubleshooting

• "The scheduler last ran N minutes ago": Magento cron is not running every minute. Check the server crontab and bin/magento cron:run. You can run bin/magento commercegears:promo:scheduler:run by hand.
• "Missed" in the switch log: cron did not run at all during a window. The window is not started afterwards.
• A campaign started late: the switch log shows the delay; it usually means cron was busy or stopped.
• The price did not change on the storefront: check that the rule is linked and active in the Linked Rules list, that the product matches the rule, and that the customer group and website fit. With an external cache other than Magento's built-in cache or Varnish, clear it for the product.
• A rule is switched off although I need it: an enabled campaign that has not started yet holds its rules off. Remove the rule from the campaign, or switch the setting off.

13. Uninstall

Disable or delete campaigns first if you want their rules in a defined state, then:

composer remove commercegears/module-promo-scheduler
bin/magento setup:upgrade

Rules created by the module stay in Marketing > Cart Price Rules and Catalog Price Rules.