Recurring Orders

Automatically repeat a recipient's order on a weekly, fortnightly, or monthly schedule, with stock checks and confirmation flows built in.

Overview

Recurring orders let recipients opt in to automatic re-ordering. After completing an order, a recipient can set up a recurring schedule. The system then creates new orders automatically at the chosen frequency, cloning items from the original (source) order. Admins can monitor, pause, resume, or cancel recurring configurations from the admin panel.

A scheduled command (app:recurring-orders:create) runs via cron to process due configurations and create orders.

Key Concepts

• Recurring order config -- The configuration record that drives automatic ordering. It links a customer to their source order, stores the frequency, tracks the next scheduled date, and holds the active/paused/cancelled state.
• Source order -- The completed order that a recurring config is based on. Items are cloned from this order each time a new order is created.
• Frequency -- How often the order repeats. Options are weekly, fortnightly (every two weeks), or monthly. Your food bank's settings control which frequencies are available.
• Next scheduled date -- The date when the system will next attempt to create an order. Calculated based on the pickup location's delivery schedule.
• Confirmation hash -- A secure token used when the system needs the recipient to confirm an order (e.g. when some items are out of stock).

Recurring order states

A recurring order config can be in one of three states:

| State | isActive | pausedAt | Description | |-----------|------------|-------------|------------------------------------------------------| | Active | true | null | The system will create orders on schedule. | | Paused | false | set | Temporarily stopped. Can be resumed by an admin. | | Cancelled | false | null | Permanently stopped. A new config must be created. |

Only one active config can exist per customer at a time. Creating a new config automatically cancels any existing active one.

How It Works

Creating a recurring order (recipient side)

1. The recipient completes an order through the normal checkout flow.
2. From their account area, they choose to set up a recurring order based on a completed order.
3. They select a frequency (weekly, fortnightly, or monthly) from the options your food bank allows.
4. The system validates the frequency, checks that the source order has a pickup location, and calculates the first scheduled date.
5. Any existing active config for this customer is cancelled.
6. The new config is saved with isActive = true.

How the schedule is calculated

The schedule calculator uses the source order's pickup date and the pickup location's delivery day to determine future dates. All calculations respect your food bank's configured timezone.

Weekly: Finds the next occurrence of the pickup location's delivery day after the source order date. If the delivery day has changed at the location since the original order, the current delivery day is used instead.

Fortnightly: Finds the next delivery day, then skips ahead one additional week to land approximately two weeks from the reference date.

Monthly: Finds the delivery day in the next month that falls closest to the same day-of-month as the original pickup. For example, if the original pickup was on the 15th and the location delivers on Wednesdays, the system picks the Wednesday nearest the 15th of the following month. If the target day exceeds the month's length (e.g. the 31st in February), it targets the 1st of the following month instead.

After each order is created, the schedule advances to the next date using the same logic.

The cron process

The app:recurring-orders:create command runs on a schedule (typically daily) and processes all due configs. For each config whose nextScheduledDate is in the past or present:

1. Max order check -- Verifies the customer has not reached their order limit.
2. Item availability check -- Checks whether the source order's items are currently in stock.
3. Order creation -- If all items are available, the system clones the items, creates a new order, and runs it through the checkout workflow (select pickup location, confirm, select payment, complete).
4. Schedule advance -- Updates the config's nextScheduledDate to the next future date.
5. Email notifications -- Sends a confirmation email to the recipient.

Stock availability handling

When the system detects stock issues, it follows different paths:

• All items unavailable: The order is skipped entirely. The schedule advances to the next date.
• Some items unavailable: The config is paused and marked as "awaiting confirmation". The system sends a confirmation email to the recipient with a secure link. The email lists which items are available and which are not. The recipient can confirm they want to proceed with the available items, or take no action.
• Some items skipped during creation: If items become unavailable between the availability check and order creation, the order is created with the available items only. A stock issue notification email is sent to the recipient listing the skipped items.

Confirmation flow

When stock issues trigger a confirmation requirement:

1. The system generates a confirmation hash and stores it on the config.
2. An email is sent with a link containing the config ID and hash.
3. The recipient clicks the link to view available and unavailable items.
4. If they confirm, the order proceeds with available items.
5. The confirmation URL uses your food bank's hostname.

Email notifications

The system sends three types of email related to recurring orders:

| Email | When sent | |------------------------------|-------------------------------------------------------| | Order created | After a recurring order is successfully created | | Stock issue | When some items were skipped due to stock problems | | Confirmation required | When some items are unavailable before order creation |

All emails are sent to the customer's email address and include relevant details such as the pickup location, pickup date, frequency, and item lists.

Common Tasks

View recurring order configurations

1. Navigate to Recurring Orders in the admin panel (/admin/recurring-orders).
2. The page lists all configs for your food bank, showing the customer, frequency, status, next scheduled date, and source order.

Pause a recurring order

1. Open the Recurring Orders page.
2. Find the config you want to pause.
3. Click the Pause action.
4. The config becomes inactive with a pausedAt timestamp. No further orders will be created until resumed.

Resume a recurring order

1. Open the Recurring Orders page.
2. Find the paused config.
3. Click the Resume action.
4. The system recalculates the next scheduled date from today based on the pickup location's delivery schedule, sets the config back to active, and clears the pausedAt timestamp.

Cancel a recurring order

1. Open the Recurring Orders page.
2. Find the config you want to cancel.
3. Click the Cancel action.
4. The config is set to inactive permanently. The customer would need to create a new recurring order from their account to restart.

FAQ

How does a recipient set up a recurring order? From their account area after completing an order. They select a completed order and choose a frequency.

Can a recipient have multiple active recurring orders? No. Only one active config per customer is allowed. Creating a new one cancels the previous one.

What frequencies are available? Weekly, fortnightly (every two weeks), and monthly. Your food bank's settings control which frequencies are offered.

What happens if the pickup location changes its delivery day? The schedule calculator uses the pickup location's current delivery day. If the day changes, future orders will align to the new day.

What happens if items go out of stock? If some items are unavailable, the system pauses the config and emails the recipient a confirmation link. If all items are unavailable, the order is skipped and the schedule advances. If items become unavailable mid-creation, the order is created with available items and a stock issue email is sent.

Can admins create recurring orders on behalf of recipients? No. Recurring orders are created by recipients from their account area. Admins can only manage (pause, resume, cancel) existing configs.

How often does the system check for due orders? The app:recurring-orders:create command should be set up as a cron job. The recommended frequency is daily, but it depends on your operational needs.

What timezone are scheduled dates stored in? Schedule calculations are performed in your food bank's configured timezone. The resulting dates are stored in UTC in the database.

Does the system check order limits? Yes. Before creating an order, the system checks whether the customer has reached their maximum order allowance. If they have, the order is skipped and the schedule advances.