Learning PathModule

Recurring Orders for B2B

Automate repeat purchasing for B2B replenishment with Recurring Orders, the right price-selection mode, and a recurrence schedule.

Ask about this Page
Copy for LLM
View as Markdown

After completing this page, you should be able to:

  • Explain how a Recurring Order is created from a Cart and inherits its Business Unit and Store.

  • Choose between Fixed and Dynamic price selection for a replenishment scenario.

  • Configure a recurrence schedule using a Recurrence Policy.

Horizon Hotels restocks the same room-electronics kit on the first of every month across dozens of properties. Manually rebuilding and submitting that order each cycle is exactly the repetitive work B2B replenishment should automate. The Recurring Order resource turns a one-time Cart into a standing instruction that generates Orders on a schedule.
A Recurring Order is not the same as a reorder. A reorder is a buyer manually repeating a past purchase by replicating a Cart or Order, as covered in The B2B Cart. A Recurring Order removes the manual step: it generates Orders automatically on a schedule, with no buyer action each cycle. Choose a Recurring Order when the cadence is fixed and predictable, and a reorder when a person decides, each time, whether to buy again.

How a Recurring Order is built

A Recurring Order is created from a Cart, and it inherits the Cart's Store and Business Unit automatically. You do not scope a Recurring Order directly to a Business Unit through the endpoint. Instead, assemble a properly scoped B2B Cart, then create the Recurring Order from it, and the commercial context comes along.
POST /{projectKey}/recurring-orders HTTP/1.1
Content-Type: application/json

{
  "key": "horizon-monthly-room-kit",
  "cart": { "typeId": "cart", "id": "{cartId}" },
  "cartVersion": 12,
  "startsAt": "2026-07-01T00:00:00.000Z"
}
Recurring Orders are managed through the top-level /{projectKey}/recurring-orders endpoint, not an as-associate path, and there are no Recurring-Order-specific Associate permissions. Scope and ownership flow from the source Cart, so the access control you want is the access control you apply to the Cart it is built from.

Recurrence lives on the Cart's Line Items

What recurs, how often, and at what price is defined on the Cart before you create the Recurring Order. Each Line Item carries recurrence information through the setLineItemRecurrenceInfo action (or at add-line-item time), which references a Recurrence Policy and sets a price-selection mode.
POST /{projectKey}/as-associate/{associateId}/in-business-unit/key=horizon-hotels/carts/{cartId} HTTP/1.1
Content-Type: application/json

{
  "version": 11,
  "actions": [
    {
      "action": "setLineItemRecurrenceInfo",
      "lineItemId": "{lineItemId}",
      "recurrenceInfo": {
        "recurrencePolicy": { "typeId": "recurrence-policy", "key": "monthly-first" },
        "priceSelectionMode": "Fixed"
      }
    }
  ]
}

Fixed versus Dynamic price selection

The most consequential decision is how each recurrence prices its Line Items. The priceSelectionMode field offers two options.
Use PriceSelectionMode as the canonical reference. For Horizon Hotels' contracted kit, choose Fixed so every monthly Order keeps the agreed rate captured when the Recurring Order was created. For a buyer whose pricing is tied to a fluctuating commodity, choose Dynamic so each cycle re-resolves the current Channel-scoped Price.
priceSelectionMode is a beta feature. Confirm its availability for your Project before committing a design to it, and note that beta behavior may change.

Defining the schedule with a Recurrence Policy

The cadence itself is a separate Recurrence Policy resource, referenced by the Line Item's recurrence info. A policy carries one schedule, of one of two shapes.
Use StandardSchedule for fixed intervals, such as every 2 weeks. Use DayOfMonthSchedule when the buyer expects a specific day each month, such as the first day of the month.
POST /{projectKey}/recurrence-policies HTTP/1.1
Content-Type: application/json

{
  "key": "monthly-first",
  "name": { "en-AU": "First of every month" },
  "schedule": { "type": "dayOfMonth", "day": 1 }
}

To order on two dates in the same month, for example the 1st and the 15th, create two Recurring Orders, each with its own day-of-month policy, rather than trying to express both in one schedule.

The Recurring Order lifecycle

Once active, a Recurring Order moves through these states:

Use RecurringOrderState as the canonical state reference. For a replenishment design, the practical distinction is whether the Recurring Order is actively generating Orders, intentionally paused or ended, or blocked by a failure that needs operational attention.
Failed is not a transient blip the platform clears on its own. When an Order cannot be created, the Recurring Order transitions to Failed, records the cause in its failure field, and stops generating new Orders until the issue is resolved. It does not auto-pause, auto-retry indefinitely, or auto-cancel, so a replenishment design needs monitoring that watches for Failed and the accompanying failure message.

Worked example: Horizon Hotels' monthly restock

Horizon Hotels wants its room-electronics kit ordered automatically on the first of each month, at the contracted price. Sequence the design like this:

  1. Build a scoped Cart. Assemble the kit in a Cart through the as-associate / in-business-unit/key=horizon-hotels endpoint, against the Horizon Store, with each Line Item carrying the horizon-hotels-pricing distribution Channel so the contracted prices resolve.
  2. Create a Recurrence Policy. POST a DayOfMonthSchedule policy with day: 1.
  3. Attach recurrence to the Line Items. Use setLineItemRecurrenceInfo to reference the policy and set priceSelectionMode: Fixed, because the contract price must hold every cycle. (Choose Dynamic only if Horizon's pricing were meant to track the catalog.)
  4. Create the Recurring Order from the Cart. POST to /recurring-orders with the Cart reference and startsAt of the next first-of-month. The Recurring Order inherits Horizon's Store and Business Unit from the Cart.
  5. Monitor for Failed. Add an operational check for the Failed state so an out-of-stock item surfaces instead of silently skipping a month.

Horizon now has a standing monthly Order at the contracted price, scoped to its Business Unit, with no manual rebuild each cycle.

Key takeaways

  • A Recurring Order is created from a Cart through the top-level /recurring-orders endpoint and inherits the Cart's Store and Business Unit; there are no Recurring-Order-specific Associate permissions.
  • Recurrence is configured on the Cart's Line Items with setLineItemRecurrenceInfo, referencing a Recurrence Policy and a priceSelectionMode.
  • Fixed reuses the original price each cycle (contract-locked); Dynamic re-resolves the current catalog price. priceSelectionMode is a beta feature.
  • A Recurrence Policy holds either a StandardSchedule (interval) or a DayOfMonthSchedule (specific day); use separate Recurring Orders for multiple days in a month.
  • States are Active, Paused, Expired, Canceled, and Failed; Failed stops generation until resolved and requires monitoring.

Test your knowledge