Introduction

In modern software development, adaptability and customization are of great importance. In response to this requirement, Intershop introduced pre-integrated custom fields.
These serve as a dynamic solution that allows developers to define new attribute fields that can be seamlessly integrated into the checkout process.

To manage these custom fields, Intershop provides a versatile key-value entry system within a property file.
Each of the configured custom field contents is stored in the parent object's AV table by default, and an admin user can disable or enable it depending on the channel application.

Glossary

References

• Cookbook - Pre-Integrated Custom Fields

Relationship to Custom Attributes

ICM has a generic custom attributes mechanism that allows arbitrary key/value pairs to be attached to any extensible business object (orders, baskets, line items, etc.) without prior declaration. Custom attributes are unrestricted: Any key can be written and every stored key is always read back, regardless of its origin.

Pre-integrated custom fields are built on top of custom attributes as their persistence layer. A custom field value is stored as a regular custom attribute on the underlying object. Future implementations can use a different backend (e.g., dedicated database columns) without changing the custom fields API.

The custom fields layer provides the following advantages over raw custom attributes:

Export Behavior

Because custom field values are stored as custom attributes, any system that exports custom attributes (XML order export, order submission service, impex, etc.) automatically includes custom field values in its output. However, these values appear as part of the generic custom attributes section. They are not labeled as "custom fields" in that context, because there is no dedicated custom fields integration.

Configuration of Custom Fields

A dynamic mechanism allows developers to configure custom fields and add them to the checkout process by adding key/value pairs to a configuration file.

The configured fields are available to all channels in the environment and are not enabled by default. The next section describes how to enable them for a specific application. The required configuration can be provided to the configuration framework as key/value pair content via property file. This document uses a property file named customfields.properties as an example.

The configuration file customfields.properties is a simple resource bundle and uses the following structure:

intershop.checkout.customfield.<name>.type=<type>
intershop.checkout.customfield.<name>.position=<position>
intershop.checkout.customfield.<name>.scope.<scope>.isEditable=<true|false>
intershop.checkout.customfield.<name>.scope.<scope>.isVisible=<true|false>

The names of the fields are supported by property files that manage the localization text for the user display, as shown in the following example:

customfield.<name>.displayName=<A label displayed on the UI to identify the attribute>
customfield.<name>.description=<Textual information aiding user comprehension>

Key Definition Parameters of the Configuration

Naming Pattern for the Localization File

Custom Fields Configuration in Commerce Management

After the custom fields have been defined, they can be enabled/disabled by a system admin user in the application of a channel.

In the back office system of any channel application, under the "Cart and Checkout" tab, there is a configuration area to enable or disable predefined fields.

To access the configuration area to do so:

1. Open Intershop Commerce Management.

2. Switch to your channel.

3. Open Applications from the navigation bar and open your application.

4. Switch to the Shopping Cart & Checkout tab.

Here you can find a configuration section Custom Field Settings where you can enable or disable custom fields. Furthermore, the localized texts for the custom fields are displayed here.

Orders with Custom Fields Configured

Custom fields for orders and line items can be configured to be displayed on the corresponding detail page in the storefront. Furthermore, they are presented in the Custom Fields section of an order’s details in Intershop Commerce Management.

Pre-Integrated Locations

The following sections describe all locations in the ICM/PWA ecosystem where custom fields are already pre-integrated and surfaced without additional development effort.

REST API

Retrieving Configured and Enabled Custom Fields

For a REST client to be able to access the fields in the storefront, the configured custom field definitions must be published.

For registered customers, custom fields can be accessed via the Customer REST API. For users who do not have a customer profile (anonymous users), the Configurations REST API enables access to fields that are available for the selected shop.

{baseUrl}/customers/<customer-id>
{baseUrl}/configurations

An example of the custom fields element of a JSON response can be found below. The JSON example shows a configuration for two custom fields named commissionNumber and deliveryNote:

{
  "customFieldDefinitions": [
    {
      "description": "Information for the Commission Number",
      "displayName": "Commission Number",
      "name": "commissionNumber",
      "position": 1,
      "type": "String",
      "scopes": [
        { "isEditable": true, "isVisible": true, "name": "BasketLineItem" }
      ]
    },
    {
      "description": "Information for the Commission Number",
      "displayName": "Commission Number",
      "name": "commissionNumber",
      "position": 1,
      "type": "String",
      "scopes": [
        { "isEditable": false, "isVisible": true, "name": "OrderLineItem" }
      ]
    },
    {
      "description": "Information for the Delivery Note",
      "displayName": "Delivery Note",
      "name": "deliveryNote",
      "position": 42,
      "type": "String",
      "scopes": [
        { "isEditable": true, "isVisible": true, "name": "Basket" }
      ]
    },
    {
      "description": "Information for the Delivery Note",
      "displayName": "Delivery Note",
      "name": "deliveryNote",
      "position": 42,
      "type": "String",
      "scopes": [
        { "isEditable": false, "isVisible": true, "name": "Order" }
      ]
    }
  ]
}

Within this configuration, custom field definitions closely resemble the checkout settings. These definitions are crucial for the implementation of REST clients, as they provide descriptive names and specify where these fields are to be displayed.

As shown in the example, the "Delivery Note" refers to the basket, and the "Commission Number" refers to the items in the basket. The same fields are also assigned as read-only elements to the order and its items.

Integrations into the Checkout Process

As soon as the fields are enabled they can be used in the checkout. The fields at the basket and their line items can be viewed and edited there. The values are automatically transferred to the order/item if the configured fields are also enabled for the order and its items with the same name. In this way, they can be accessed later using the same key.

Adding and Updating Custom Fields

Once the configuration is ready, when creating or patching a basket using the POST /baskets endpoint, it is possible to include specific custom field user values by adding a body JSON as shown below. The custom fields deliveryNote and commissionNumber are configured as editable, visible, and part of the scope basket.

{
  "customFields": [
    { "name": "deliveryNote", "value": "my note for the supplier", "type": "String" },
    { "name": "commissionNumber", "value": "CN.123", "type": "String" }
  ]
}

This means that a new basket is created and contains values for two custom fields available for the basket scope. The handling for the other resources with the option to attach custom fields works in a similar way.

The same mechanism applies to basket line items (PATCH /baskets/<basketId>/items/<itemId>), orders, and order line items.

Error Handling

If a custom field cannot be edited or is not available for the scope given in the payload of the create/edit request, the response will contain a JSON element named infos with a code and a message. The request itself will not fail.

If the basket request above had an additional custom field named commissionNumber that was not available for scope Basket, the response would contain an element similar to the one below:

{
  "infos": {
    "causes": [
      {
        "code": "commissionNumber_not_found_info",
        "message": "The custom field with the name commissionNumber does not exist or is not editable in the current scope",
        "parameters": [
          { "name": "commissionNumber", "scope": "Basket" }
        ]
      }
    ]
  }
}

The same behavior applies to the creation of basket line items.

B2B: Requisitions and Approvals

In B2B scenarios, custom fields are also integrated into the order approval workflow. The RequisitionRO and the corresponding LineItemRO in the B2B Approval REST API carry customFields, making custom field values visible and accessible throughout the approval process.

Integration into After-Checkout Processes

The custom fields and their values entered during the checkout process are automatically included by the export services in the ICM and in the checkout confirmation e-mail.

ICM Backoffice

Custom fields are pre-integrated in two places in the ICM Backoffice:

Order Detail Page

The order detail view (ViewSellerOrder_52 pipeline) automatically loads all custom field values for an order using the GetAllOrderCustomFieldValue pipelet. The values are displayed inline in the order summary section of the order details page (OrderDetails_52.isml).

Line Item Detail Page

For each order line item, all custom field values are loaded via the GetAllOrderLineItemCustomFieldValue pipelet and rendered in a dedicated Custom Fields section in the line item detail view (LineItemDetails_52.isml).

Both views display all configured custom fields regardless of their isVisible or isEditable flags. The back office always shows the full set of field values for the order.

E-Mails (B2C)

The Order Confirmation E-Mail is pre-integrated with custom fields on both the order and line item level.

The ConfirmationMailOrderCreationHandler populates two template variables:

These variables are available in the ISML templates:

• OrderEMailNotification.isml: Renders order-level custom fields in a table below the order date.

• LineItemDetails.isml (shared fragment): Renders line item custom fields below each product row.

Only fields where isVisible=true for the Order / OrderLineItem scope are included.

E-Mails (B2B)

In B2B scenarios, custom fields are displayed in all order-related notification e-mails. The shared template fragment BasketInfo.isml renders both basket-level and line item custom fields. This fragment is included in the following e-mails:

The BasketInfo.isml fragment reads BasketCustomFieldValues (basket scope) and LineItemCustomFieldsMap (basket line item scope) from the pipeline dictionary and renders them inline.

Basket Clone and Recurring Orders

When a basket is cloned (for example, to create a recurring order or to convert a quote into an order), custom field values are automatically copied from the source basket to the target basket.

Only fields where isVisible=true for the respective scope are transferred during cloning.

Impex and Other Export Mechanisms

There is no dedicated custom fields integration in impex, the XML order export, the Order Submission Service, or other export/integration mechanisms. These systems operate on the custom attributes layer, not the custom fields layer.

Because custom field values are stored as custom attributes on the underlying object, they automatically appear in the output of any mechanism that exports custom attributes—but as generic key/value entries in the custom attributes section, not labeled as "custom fields". See Relationship to Custom Attributes for details.

PWA (Angular Storefront)

The Intershop PWA has full pre-integrated support for custom fields across the checkout and account flows.

Definition Loading

When the PWA initializes, it loads all custom field definitions from the ICM REST API alongside the general server configuration:

• Anonymous users: Definitions are fetched from the /configurations endpoint.

• Authenticated users: Definitions are fetched from the customer endpoint.

The definitions are stored in the NgRx ServerConfigState and are available throughout the application without additional fetching. If the active locale differs from the default locale, the PWA also fetches localized display names and descriptions for the field labels separately.

Relevant selectors available to any component:

Writing Custom Field Values

The CheckoutFacade is the primary interface for components:

• customFieldsForScope$(scope): observable of definitions for a scope

• setBasketCustomFields(customFields): persists basket-level custom field values

Internally, setBasketCustomFields() dispatches an NgRx action. The effect fetches the current scope definitions, converts the frontend key-value map to the REST wire format via CustomFieldMapper.toData(), and issues a PATCH request to the basket endpoint. Line item custom fields are written via line item update actions using the same mapper.

UI Components

The PWA ships five pre-built components for custom fields:

Page-Level Integration

Custom fields are pre-integrated in the following pages without any custom development required:

The basket page is the primary entry point: ish-basket-custom-fields renders a collapsible section where the user can add or edit values. The same values then follow the order through all subsequent pages as read-only information.

B2B

In B2B scenarios, the same components are reused without modification.

Since PWA 9.1.0, ish-basket-custom-fields-view additionally accepts a Requisition entity, so custom field values are visible in the order approval workflow alongside the requisition details. (In PWA 9.0.0, the component was already present but the requisition detail page did not yet include it.)

Pipeline API

For pipeline-based integrations, the following pipelets are provided:

In bc_custom_fields (general-purpose):

In sld_ch_consumer_plugin (back office order views):

Java API

For Java-based integrations, the core API is provided by bc_custom_fields: