Introduction

Welcome to the Intershop Recurring Order Extension, an extension that provides the Recurring Order Service and corresponding REST APIs for your Intershop Commerce Management installation.
This release note provides important insight into product version details, dependencies, and comprehensive setup and configuration instructions to optimize your integration process.

References

• Concept - Recurring Orders

• Cookbook - Recurring Orders

• Job - Recurring Order Schedule Service (Recurring Order Extension)

Version Information and Dependencies

This delivery and the accompanying documentation are valid for the following combinations of software versions:

(*) See hints (manual steps/restrictions) regarding storefront integration described in Storefront Integration.

Delivery

The table below provides information about the cartridges included in the package:

The image is available in the respective Docker repository: intershophub/icm-as-customization-recurringorders.

Supported Application Types

The Recurring Order Extension can be used for the following application types:

(*) See hints (manual steps/restrictions) regarding storefront integration described in Storefront Integration.

Feature Overview

The recurring order feature is a storefront feature that allows users to repeatedly place orders based on a type of order template and a fixed schedule. It is available for B2C as well as for B2B customers and can be enabled/disabled per channel, see Configuration.

REST API

The Subscription (Recurring Order) REST API that came with the standard ICM was removed with ICM 13.0.0. Instead, you can use the Recurring Order REST API provided by the Recurring Order Extension. Make sure that the accept header contains: application/vnd.intershop.recurringorder.v2+json.

For version Recurring Order/2.0.0, see Reference - Recurring Order Extension REST API 2.0.0.
For version Recurring Order/2.1.0, see Reference - Recurring Order Extension REST API 2.1.0.

Update Owner of a Recurring Order

For version Recurring Order/2.1.0+, the REST API supports updating the owner of a recurring order. This enhancement makes it possible to transfer ownership of recurring orders, for example, when a B2B user leaves the company and another user needs to assume responsibility for those orders. If B2B users are removed without re-assigning their recurring orders, all entries are automatically assigned to the (first) account admin.

Storefront Integration

Create Recurring Order

If the recurring order feature is enabled, the shopping cart will have a One-time purchase and Recurring order option.

When Recurring order is selected, additional fields to set the recurrence will be displayed.

Recur every: Mandatory recurrence interval (i.e., how often orders should be triggered)
Start from: Mandatory start date, which can be today (default) or a future date
Until: Optional end date, which is any date after the start date
Until after: Optional number of orders after which the recurring order will automatically end

After selecting Recurring order, the subsequent steps up to the checkout must be carried out as usual.

The list of payment methods is usually limited, as the orders are created without user interaction. For example, it is not possible to log in to the payment service provider.

In case of a B2B order with the approval service activated, all recurring orders must be approved by default. For a B2C customer, the recurring order is created immediately after clicking the Submit recurring order button.

Get List of Recurring Orders

B2C customers and B2B users can view the list of available recurring orders by clicking Purchases | Recurring orders.

In addition, the B2B account administrator can see the list of their recurring orders as well as the list of recurring orders of the client (organization).

Get Recurring Order Details

Clicking on the recurring order document number will take you to the recurring order details page. In addition to the usual information about the buyer, addresses, line items, shipping method, etc., the top part contains special information about the recurring order. For example, you can see when the last order was created, when the next order is scheduled, and how many orders have been created in total. If there are already orders based on this recurring order, the numbers of last 5 orders are also displayed and linked here.

Enable/Disable a Recurring Order

Recurring orders can be paused at any time, as often and as long as required without giving reasons. To do this, the entries can be deactivated both in the list and in the detail view using the slider. If a recurring order is inactive, no orders are generated.

Delete a Recurring Order

Following the general pattern, a single recurring order can be deleted from the list view by clicking on the trash can icon.

Recurring Order Marketing Include (since ICM 13.2.0)

Independent from this extension, a new include Basket - Order Summary Recurring Order Marketing is available from ICM 13.2.0. This include allows to add marketing information related to recurring orders.

This include is only used in the PWA and is placed directly below the Recurring order section in the basket. It can contain various components, such as text, images, videos, HTML snippets, etc. Since these elements promote the recurring order feature, they are always visible, even when the One-time purchase option is selected. When the Recurring order option is selected and the promotional conditions are met, the promotion appears with a Details link that provides additional information.

ICM Back Office Integration

Feature Flag

See Configuration | Feature Flag.

List of Recurring Orders

The Recurring Orders Extension adds a Recurring Orders menu entry beneath Orders at the channel level in the Intershop Commerce Management back office.

This page automatically displays all recurring orders for the channel. Users can narrow down the results by searching by recurring order number, customer, or next order date. Additionally, users can sort some columns by clicking on the column headers.

Currently, only a list view of recurring orders is available. Links to the last order or customer lead directly to the respective order or customer details page.

Promotion Condition for Recurring Orders (since 2.2.1)

Version 2.2.1 of this extension introduces a new promotion condition for recurring orders. This feature is only available with this extension.

You can use it to set up a promotion that offers discounts on recurring orders.

You can provide an order range in the condition details to limit the discount to a certain order range, see the examples.

The promotion condition for recurring orders can be combined with existing promotion conditions, e.g., receive a discount when there are more than five items in the cart or when special products are included or excluded (Item Inclusion/Exclusion condition). The discount can be an order discount or an item discount (for particular items or all items).

It is also possible to run multiple promotions based on recurring order conditions. These promotions could be applied simultaneously, staggered over time, or vary depending on the product assortment.

For more information on how to extend the messaging for the recurring order promotion to directly show customers the benefits of the promotion, see Recurring Order Marketing Include.

Setup

The Recurring Order Extension customization image is available from Intershop's public repository.

Helm Declaration of Extension for Deployment

To add customization to Helm values:

1. Declare the customization image.

2. Add feature cartridge ft_recurringorders to the cartridge list, see Concept - Customization - Deployment - ICM 11+.

icm-as:
  customizations:
    recurringorders:
      repository: intershophub/icm-as-customization-recurringorders:2.0.0
...
  environment:
    CARTRIDGE_LIST: "ft_icm_as ft_recurringorders"

Using Docker Compose to Start the Server with the Extension Image

To prepare the start of ICM with the Recurring Order extension, make sure that all required services, the MSSQL database, and the web server are started.

Modify the compose file to specify which cartridges the ICM should load. This is done by setting the CARTRIDGE_LIST environment variable on the application server:

services:
    customize-recurringorders:
        image: intershophub/icm-as-customization-recurringorders:<TAG>
        volumes:
            - customizations:/customizations
...
    appserver:
        depends_on:
        - customize-recurringorders
...
        environment:
            # ... more environment variables ...
            # Example cartridge list. Please adapt to your requirements.
            CARTRIDGE_LIST: "ft_icm_as ft_recurringorders"
...

When the application server is started, the feature is available without any DB preparation steps.

Adapt Customization Project

To add the customization to your project, you must add it to your customization dependencies.

Follow these steps:

1. Register the customization image in your main build.gradle.kts:

   val icmDockerRegistry = "docker.tools.intershop.com/icm/intershophub"
   // specified in gradle.properties
   val recurringOrdersVersion: String by project
   
   intershop {
       projectConfig {
           modules {
               // ... other modules ...
   
               register("recurringorders") {
                   dependency.set("com.intershop.recurringorders:recurringorders:${recurringOrdersVersion}")
                   image.set("${icmDockerRegistry}/icm-as-customization-recurringorders:${recurringOrdersVersion}")
                   testImage.set("${icmDockerRegistry}/icm-as-customization-recurringorders:${recurringOrdersVersion}")
               }
           }
       }
   }
   
   subprojects {
       // ... other settings ...
    
       plugins.withType<JavaPlugin> {
           dependencies {
               // ... other dependencies ...
    
   	        cartridge(platform("com.intershop.recurringorders:recurringorders_versions:${recurringOrdersVersion}"))
               implementation(platform("com.intershop.recurringorders:recurringorders_versions:${recurringOrdersVersion}"))
            }
       }
   }

2. For Responsive Starter Store integration, the REST API cartridge has to be added to the application cartridge list.
   Add the dependency of the REST API cartridge to your Responsive Storefront application cartridge (e.g., app_myproject/build.gradle.kts):

   dependencies {
       // ... original dependencies ...
   
       // Recurring Order Extension
       cartridgeRuntime ("com.intershop.recurringorders:app_sf_rest_recurringorder")
   }

   Also add the REST API cartridge to your Responsive Storefront applications in your apps.component:

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <components xmlns="http://www.intershop.de/component/2010" scope="global">
   	<fulfill requirement="selectedCartridge" of="intershop.B2CResponsive.Cartridges" value="app_sf_rest_recurringorder" />
   	<fulfill requirement="selectedCartridge" of="intershop.SMBResponsive.Cartridges" value="app_sf_rest_recurringorder" />
   </components>

3. Define recurringOrdersVersion in your gradle.properties:

   ...
   recurringOrdersVersion = 2.0.0
   ...

4. Start your application server in development mode:

   • Use Gradle to manage the server instance by using the command gradlew startAS,

   • Run gradlew tasks to see available tasks or check for further options.

For details on customization, see:

• Concept - Customization - Development - ICM 11+

• Concept - Customization - Deployment - ICM 11+

Configuration

Feature Flag

The Recurring Orders Extension adds a Recurring Orders preference section to the Intershop Commerce Management back office where you can enable/disable the feature for the channel.

Schedule Service

Time-based Order Creation

The Recurring Order Extension automatically creates a job Recurring Order Schedule Service in the domain root and application system that is responsible for creating orders for each recurring order.

You can find it in the SMC Scheduling view.

The schedule (run time) of the service determines when recurring orders are triggered. In this example, the service runs daily at 9:00 AM. Since recurring order schedule dates are stored without time information (only the date is recorded), all orders due or overdue on that date will be generated.

After the job has been successfully executed, the total number of orders created can be viewed in the job’s Attributes tab.

Manual Order Creation (since 2.2.1)

Starting with version 2.2.1, you can manually trigger order creation for recurring orders. This could be useful either for testing purposes or if an additional delivery outside the planned schedule is necessary.
To do this, copy the IDs of the corresponding recurring orders as a comma-separated list (xxx,xyz,zzz) into the “ManualOrderCreation” field of the Recurring Order Scheduling Service job. If there are entries in this field, only these will be processed and not scheduled ones. This job can be repeated as many times as desired, and a new order will be generated each time for all specified IDs, regardless of whether an order was previously scheduled. After each order, the date of the next order is recalculated and set accordingly.

The ID of a recurring order is the string in the URL, as shown in the picture.

Changelog

Version Recurring Order/2.2.1

• Added new promotion condition

• Added customer e-mail to the error when an order could not be created

• Provide information about promotions & discounts via REST API

• Added possibility to execute a manual order creation

• General improvements & fixes

Version Recurring Order/2.1.0

• Improved accessibility for e-mail templates

• Support of recurring order owner transfer (B2B only)

• General bug fixes (dependency problems)

Version Recurring Order/2.0.0

• Support of ICM 13.0.0

• Show last 5 orders in recurring order details (storefront)

• Fix/rework e-mail templates especially for B2B (requisitions for recurring orders)

• Show list of recurring orders in ICM back office (including search & sorting)

• Internal rework: Use direct method calls instead of REST for inside communication

• General improvements & fixes