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:

The PWA uses the REST API provided by the Recurring Order Extension to retrieve recurring order lists, details etc.

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:

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 section Configuration.

REST API

There is is a new major version of the Recurring Order REST API provided by the Recurring Order Extension. To use it, the accept header should contain:
application/vnd.intershop.recurringorder.v2+json, see Reference - Recurring Order Extension REST API 2.0.0.

The previous version of the existing Recurring Order REST API that comes with the standard ICM will be removed with the next major release.

PWA 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 where you can set the recurrence will be displayed.

Recur every: Mandatory recurrence interval. How often should orders 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 the 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.

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.

Setup

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

Helm Declaration of Extension for Deployment

Add customization to helm values:

• Declare the customization image

• 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:1.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.

Customize the Extension

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

Therefore, 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. Add dependencies to your project's feature definition (e.g., ft_myproject/build.gradle.kts):

   dependencies {
       // base on ICM AS
       cartridgeRuntime ("com.intershop.icm:ft_icm_as")
       
       // ... more dependencies ...
   
       // Recurring Order Extension
       cartridgeRuntime ("com.intershop.recurringorders:ft_recurringorders")
   }

   To include the recurring order feature, add your project's feature definition cartridge to your development configuration within your main build.gradle.kts. If you need additional feature cartridges for local development, you can add them here as well:

   intershop_docker {
       // ... other configuration ... 
       developmentConfig {
           appserverAsContainer = true
           cartridgeList.set(setOf("ft_myproject"))
           // alternative scenario using a feature cartridge where Recurring Order isn't included as a runtime dependency:
           // cartridgeList.set(setOf("ft_recurringorders", "ft_my_other_feature_cartridge_dev"))
           testCartridgeList.set(setOf("ft_mytest"))
       }
   }

3. Define recurringOrdersVersion in your gradle.properties:

   ...
   recurringOrdersVersion = 1.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 ICM 11 - Deployment

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

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 defines when the recurring orders are triggered. In this example, every day in the morning at 09.00 AM. Since recurring order schedule dates are stored without time information (only date), all orders that are 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.

Changelog

Version Recurring Order/1.0.0

• Initial implementation for ICM 12.1.0