Recurring Orders feature overview

The Recurring Orders feature lets B2B buyers set up automated repeat purchases directly from the checkout. Once configured, the system places orders automatically at the chosen interval, sends notifications before each execution, and pauses for buyer review when prices rise beyond the tolerances the buyer has set or products become unavailable.

Concepts

Setting up a recurring order

At checkout, an eligible buyer can enable the recurring order setup widget. The buyer selects a cadence (for example, weekly or monthly), a start date, and optionally a schedule name. The every N weeks cadence also requires an interval value, and the on specific days cadence requires one or more days of the week.

When the order is placed, the system:

1. Saves a serialized snapshot of the quote—including products, quantities, prices, shipment method, and payment method—and stores the unit price of each item as that item’s reference price.
2. Creates a recurring schedule record in spy_recurring_schedule with the first trigger date resolved from the start date and the cadence.
3. Registers the schedule with the RecurringOrder state machine in the draft state and immediately activates it.

The checkout order itself is placed as usual and is not counted as a recurring execution. The start date determines when the first recurring order is placed:

• If the buyer picks a future date, the first recurring order is placed on that date, and later orders repeat from it at the selected cadence. For the on specific days cadence, the date must fall on one of the selected days.
• If the start date is today or is not set, the first recurring order is placed one cadence interval later. For the on specific days cadence, it is placed on the next selected day after today.
• A start date in the past is rejected.

A recurring schedule is only available for quotes that meet all of the following conditions:

• The quote is not locked (not sent for approval).
• The quote does not originate from a Request for Quote (RFQ).
• The customer is not a guest.
• The payment method is invoice-based (invoice, purchaseOnAccount, or a configured equivalent).

Projects can add their own conditions, and features can contribute conditions of their own. With the Purchasing Control feature installed, a quote carrying a budget that requires approval is rejected—see Budgets that require approval cannot be selected.

Cadence types

Schedule lifecycle

The recurring schedule moves through states managed by the RecurringOrder state machine. The following diagram describes the full lifecycle:

Schedule status

Buyers and Back Office users see a schedule status instead of the state machine state. The status is derived from the state:

• A stable state is a state the schedule rests in and the buyer can act on. Each stable state has its own status: active, paused, review_required, failed, cancelled, and draft. The pre_trigger_notified state is shown as active.
• A transient state is a state the schedule passes through while the system notifies the buyer, validates the schedule, or places the order: notifying, validation, confirmed, order_placed, completing, and skipped. All transient states are shown as processing.

While a schedule is processing, the storefront shows the Processing badge and hides the Pause, Cancel, and Skip actions and the next execution date. The buyer can act on the schedule again once it settles in a stable state.

Recovery of stuck schedules

If a state machine run is interrupted—for example, because the process is killed during a deployment—a schedule can stay in a transient state with nothing to move it on. A scheduled job checks every 5 minutes for schedules that have stayed in a transient state for at least 15 minutes:

• A schedule stuck in notifying or order_placed for up to 6 hours is moved on automatically, because repeating these steps cannot place a duplicate order. If the interrupted run already sent the upcoming order email, the buyer receives it a second time.
• A schedule stuck in confirmed, completing, or skipped, or stuck in any transient state for more than 6 hours, is logged for manual attention, because repeating these steps could place a duplicate order or advance the schedule twice.

For details, see Recover stuck schedules.

Buyer actions

Buyers can perform the following manual actions from the recurring order detail page on the storefront:

Notifications

The system sends the following emails to the buyer. All three use CMS blocks for their HTML and text templates, so the content is editable in the Back Office under Content > Blocks.

The Schedule Grace Period defaults to 48 hours and is configured globally in the Back Office under Configuration > Recurring Orders > General > Schedule. Individual schedules can override it.

Review Required flow

Before placing each order, the system validates the stored quote snapshot against current product and pricing data. Price increases are measured against the price tolerances of the schedule. If issues are detected, the schedule moves to the review_required state and the buyer receives a review notification email.

The buyer reviews the flagged items on the Review Required page. The following table lists common issue types. The full set of checkout error types that map to each group is configurable through getReviewReasonGroupMap() in OrderExperienceManagementConfig.

Items flagged as unavailable, out of stock, or discontinued are non-purchasable and must be removed or substituted before the order can proceed. Projects can narrow this list through getNonPurchasableReviewReasonGroups() if items of a group should stay purchasable.

Reference prices

Price validation compares the current unit price of each item with that item’s reference price—not with the price of the last order the schedule placed.

A reference price is written in exactly two moments:

• When the schedule is created, from the unit price on the checkout quote.
• When the buyer accepts a price change during a review. The accepted price replaces the stored reference for that item, so the next execution is measured against the price the buyer agreed to.

Nothing else changes it. Placing an order, skipping an execution, pausing, resuming, and editing the schedule all leave reference prices untouched.

Two consequences follow:

• A price the buyer has already accepted does not trigger a review again. The schedule re-anchors to the accepted price, and only movement beyond that point is flagged.
• Re-anchoring happens per item, and only for the items the buyer accepted. An item that was not flagged keeps its existing reference price, so increases too small to require a review stay measured against the earlier price and accumulate across executions until they exceed the item’s tolerance. A product without a tolerance has no such room: any increase is reviewed.

Available review actions

Adding products during review

The add-product search bar returns concrete products the buyer can add to the order being placed. For each added product, the buyer selects a shipping address and a shipment method:

• The shipping address choices are grouped by source: the addresses stored with the schedule itself, and the addresses of the buyer’s company business unit. Duplicate addresses are offered once.
• The shipment methods are resolved for the selected address and, in a marketplace setup, for the selected offer.

The following products are not offered in the picker, and are also rejected if they reach the server through a crafted request:

Projects can add their own restrictions. See Install the Recurring Orders feature for the extension points.

Review scope

Each change is applied with a scope:

Before the order is placed, a confirmation modal summarizes the accepted price changes, the removed items, the substituted products, and the original and new order totals.

The following guards apply while reviewing:

• The schedule can only be reviewed in its own currency and price mode. If the buyer has switched either one, the review page asks them to switch back.
• If prices change again between opening the review page and approving it, the buyer is asked to review the updated order before approving.
• If every item is removed, the order cannot be placed—a schedule cannot be executed without items. The buyer can clear this block by adding at least one product before confirming.

Price tolerances

Without tolerances, a schedule moves to Review Required on any price increase, however small. A price tolerance lets the buyer accept small increases without interrupting the order, so the order is placed automatically as long as prices stay within the limits the buyer has chosen.

Two independent checks decide whether a price increase needs review. Neither inherits from the other, and either one failing moves the schedule to Review Required.

Both checks ship switched off. Every tolerance defaults to 0, so schedules that exist before you install the tolerances behave as before: any price increase is reviewed. A product without a current price is always reviewed, whatever the settings.

Tolerance values

A tolerance is a percentage with the following limits. The same limits apply in the storefront form, in the backend validation, and in the database columns.

• The value is 0 or higher and at most 999.99.
• The value has at most two decimal places and is a multiple of the step 0.01. For example, 0.25, 0.5, 1.75, and 12.5 are valid.
• The field is required. A blank value is rejected with Enter a value. Use 0 to turn off.
• A value outside the range is rejected with Enter 0 to 999.99. A value with more decimals than allowed is rejected with Use up to 2 decimals.

Projects can change the maximum, the number of decimals, and the step. See Configure module behavior.

The comparison uses exact decimal arithmetic, without floating-point numbers. A price is accepted when it does not exceed the reference price multiplied by (100 + tolerance) / 100. For the order total, the highest accepted total is shown rounded down to a minor currency unit, such as a cent.

How the checks work together

The Ignore product price changes setting hands the whole decision to the order total. It takes effect only while the order total tolerance is above 0.

The setting defaults to off. It cannot be saved while the order total tolerance is 0, because no price check would remain. The save is refused with Set an order total tolerance above 0 to ignore product price changes. This also applies when the order total tolerance is set back to 0 while the setting is still selected.

Set tolerances on the storefront

On the recurring order detail page, the Details sidebar shows a Price tolerance row with the current state and an Edit link to the Price tolerances page. The row reads:

The Order items table has a read-only Price tolerance column. A cell shows +5% for a product with a tolerance above 0, Any increase for a product at 0, and Order total while product price changes are ignored. An information icon in the column header opens a popup that explains the values. When the order total tolerance is above 0, the footer of the table also shows the highest total that is placed automatically.

The Price tolerances page, /recurring-orders/{uuid}/price-tolerances, lets the buyer edit all tolerances of a schedule in one place.

The page contains the following:

While Ignore product price changes is selected, the products section collapses to the notice Product price changes are ignored: only the order total is checked. This happens as soon as the box is selected, before saving, and when the page opens with the setting already saved. The product tolerances stay in the form and are kept when the box is cleared again.

Save stores the values and returns to the recurring order detail page with a success message. Cancel discards the changes. A note above the buttons states that the changes apply from the next order on the next trigger date.

Bulk editing

A recurring order can contain dozens of products, so the products section supports editing several products at once. Bulk editing is a state of the same page, not a separate page or mode, and the single Save persists row changes and bulk changes together.

• Each product row has a checkbox, and the table header has a select-all checkbox. The select-all shows an indeterminate state while only some rows are selected. A counter shows how many products are selected, for example 3 products selected.
• With at least one row selected, a bar appears above the table. Enter a tolerance under the same rules as a single row and select Apply to write it to every selected product. Unselected rows are not changed, and the applied values appear immediately in each row and in its trigger price.
• Turn tolerance off resets every selected product to 0, so any increase on those products is reviewed again.
• The select-all checkbox in the table header clears the selection and leaves all values untouched.

Who can edit tolerances

Any company user who can view a schedule can also edit its tolerances. Edit rights follow the visibility permissions. There is no ownership check and no separate permission.

Tolerances are locked during a review

Validation has already run against the stored tolerances when a schedule is in review_required, and a change would not re-run it. For that reason, tolerances and the Ignore product price changes setting cannot be changed in this state:

• The sidebar still shows the current tolerance, but an information icon replaces the Edit link. Its popup states Tolerances cannot be changed while this order is under review.
• Opening the Price tolerances page directly shows the values read-only, shows the same sentence at the top, and offers no Save button and no bulk editing controls.
• A save request for such a schedule is rejected by the backend, so the lock does not depend on the page hiding the button.

Editing is available again as soon as the review is resolved and the schedule returns to active. Accepting or rejecting a review does not change the stored tolerances.

Tolerances on the Review Required page

On the Review Required page, a product that exceeds its own tolerance shows the reason Price above 0.5%, using the tolerance of that product. A product without a tolerance keeps the reason Price increased. A product that is flagged only because the order total rose, but stays within its own tolerance, is marked with a note such as within your 0.5% tolerance.

When the order total tolerance is breached, the summary at the top of the page states the previous and current totals, the increase in percent, and the tolerance, for example This order’s total rose from €914.74 to €933.80 (+2.1%), above your 2% tolerance. If no single product exceeded its own tolerance, the page says so instead of showing an empty list of flagged items: No single product exceeded its own tolerance — it is the order total that rose.

When the buyer confirms the review, the same tolerances are applied to the re-validation, so the buyer is never blocked at approval on an increase that the pre-placement check accepted. Approving accepts the drifted prices as the new reference prices for the chosen review scope. If a price or the total rose again since the page was shown, the approval is refused and the buyer is asked to review the updated order.

Marketplace and shipment support

Recurring schedule items keep their merchant reference and product offer reference, so schedules created in a marketplace setup are re-placed against the same offers. When the buyer adds a product on the Review Required page and the product is sold by several merchants, an offer selector is displayed.

Products added during review must be shippable with a delivery-like shipment type—by default delivery or on-site-service, in that preference order. When an offer or store exposes several supported types, the first one is used. The system resolves the available shipment methods for the added item and rejects products for which no shipment method, availability, or price can be resolved.

Execution history

Each recurring schedule maintains a full execution history. Every significant event is recorded:

Storefront pages

Back Office

Back Office users manage recurring order schedules under Sales > Recurring Order Schedules. The page is read-only—it is intended for oversight and support, not for editing schedules on the buyer’s behalf.

Recurring Order Schedules list

The list shows the following columns: Name, Company, Business Unit, Owner, Status, Frequency, Cycle Total, Price Tolerance, Next Trigger Date, and Last Execution. The Price Tolerance column shows On when the schedule has an order total tolerance or at least one product tolerance above 0, and Off otherwise. It is sorted by next trigger date in ascending order by default, and can be searched by name.

The following filters are available:

Total Committed Recurring Volume

Above the list, the Total Committed Recurring Volume widget shows the recurring order volume of the current month. The total combines two inputs, and the widget shows both the combined figure and the split between them:

Below the figures, a run-rate line summarizes the split—for example, how many orders have already been placed and how many active schedules are still due. When neither input returns anything, the widget reports that there is no recurring order activity for the month.

Totals are grouped by currency, so a multi-currency shop gets one figure per currency. The widget is global—it is not affected by the list filters.

By default, the period covers the whole current calendar month. Projects can narrow it to the remainder of the month instead; the bounds apply to both inputs at once, so the already-placed and still-planned figures always describe the same period.

The forecast is not recalculated on each page load. A scheduled job recalculates it and stores it as a snapshot in spy_recurring_schedule_forecast, and the Back Office reads the stored snapshot. Because of that, the displayed value reflects the last refresh rather than the current second.

Schedule detail view

Opening a schedule shows its configuration, the buyer and company it belongs to, the schedule items with their quantities and merchant names, and a link to the source sales order the schedule was created from. Items that belong to a configurable bundle also show the bundle name. The details list shows an Order Tolerance row with the order total tolerance, or Off when it is 0. The items table has a Price Tolerance column that shows the tolerance of each product together with the price above which the product is reviewed, for example 0.5% (336.72 EUR). The column is empty for products without a tolerance.

The tolerances are displayed only. Back Office users cannot change them, which keeps the area read-only.

B2B visibility and permissions

By default, a buyer can only view their own recurring schedules. Company users with additional permissions can view schedules across their organization:

These permissions are registered as company role permissions and assigned in the Back Office under Customers > Company Roles.

Cost centers and budgets

With the Purchasing Control feature installed, a recurring order carries a cost center and a budget:

• The selected cost center and budget are displayed on the recurring order detail page, together with a budget usage summary: the total budget amount, the amount already used, the amount remaining, and a bar showing the used percentage.
• The buyer can change them when editing the schedule and when approving a review. In both forms, selecting a cost center and a budget is mandatory.
• Only active cost centers of the buyer’s company business unit are offered, and only in the currency of the recurring order. If the cost center assigned to a schedule is later deactivated, it is no longer displayed on the detail page and the buyer has to select an active one the next time they edit the schedule or approve a review.
• The selected budget must belong to the selected cost center. The form is rejected if it does not.

Budgets that require approval cannot be selected

A recurring order is placed unattended by the state machine, so it cannot wait for a human approval decision at placement time. For that reason, budgets whose enforcement rule requires approval when the budget is exceeded are not offered in the recurring order budget selector.

The same rule is enforced at checkout. If a quote that is being set up as a recurring order carries a budget with the require approval enforcement rule, checkout is blocked and the buyer is asked to select another budget. This check applies regardless of the quote grand total and of the remaining budget amount—the budget does not have to be exceeded for the block to take effect. A regular, non-recurring checkout is not affected.

Only budgets bound to the following enforcement rules can be selected:

If a cost center has only approval-bound budgets, no budget choices are rendered for it. Buyers who need to assign such a cost center to a recurring order must first have a budget with the block or warn enforcement rule set up for it.

Without the Purchasing Control feature, these fields are not rendered and recurring orders behave as described in the rest of this document.

Attention banner

When a buyer has schedules in the paused, review_required, or failed states, an attention banner is displayed on the storefront. The banner shows the count of schedules requiring attention and provides quick-access links to filter the recurring order list by each status.

Related documents

• Install the Recurring Orders feature