Document Tree
Document Properties
Last Modified
Added to KB
Public Access
Doc Type
  • ICM 7.10
  • ICM 11
Concept - OCI Punchout (valid from 7.10.17)



This concept is valid for ICM version 7.10.17 and higher. For previous versions see Concept - OCI Punchout (7.8 - 7.10.16).

With the OCI Punchout feature the Commerce Management application offers an external catalog interface (OCI) for B2B customers. Hereby external systems can access product data from an Intershop server or a selection of products. Therefore the official OCI transfer format is utilized. The Punchout format can be configured on application level or during runtime individually with customer-specific settings.


OCIOpen Catalog Interface (OCI) is one of the standard formats used by ERP/Purchasing Systems when connecting to external Punchout catalogs.


The following documentation is related to the OCI Punchout feature:


To understand the OCI Punchout, a list of features for storefront and account administration is given below.

Storefront Features

OCI Checkout

An external (procurement) system can log as OCI Punchout user onto an Intershop Commerce Management storefront, browse the storefront, add products to the cart and transfer a cart back to the caller (initially identified by the HOOK_URL). Certain parts of the storefront (e.g., footer) are hidden to improve the shopping experience coming from an external system (e.g., procurement).

Product DetailsLogin to the storefront as OCI Punchout user and display product details in the OCI Punchout format for a given PRODUCTID.
Validate ProductLogin to the storefront as OCI Punchout user and automatically transfer back product details in the OCI Punchout format for a given PRODUCTID and QUANTITY.
Background SearchLogin to the storefront as OCI Punchout user and have all products displayed in the OCI Punchout format that match a given SEARCHSTRING.

Administration Features

User CreationAccount admins can create an OCI Punchout user.
Edit UserAccount admins may update the OCI Punchout users' e-mail and password.
Punchout ConfigurationAccount admins are able to configure given fields of the Punchout format by defining their content (transform) and optionally providing a formatting.

REST Features

List Punchout UsersShows all customer- and Punchout-specific users
User CreationAccount admins can create Punchout users.
Edit UserAccount admins may update a Punchout user's email or password and set them active/inactive.
Punchout ConfigurationAccount admins are able to configure given fields of the Punchout format by defining their content (transform) and optionally providing a formatting.
Delete UserAccount admins can delete a Punchout user.
OCI Punchout DataRetrieve basket line item or product data depending on customer-specific Punchout configuration


This chapter describes technical insights of the OCI Punchout standard.

OCI Transfer Format

The OCI data is transferred using hidden input fields of an HTML form with a defined field name including an index starting with 1.

Example Response
<form name="form" method="post" action="123" data-testing-id="oci-basket">
    <input type="hidden" name="NEW_ITEM-DESCRIPTION[1]" value="Sony VPL-SW225">
    <input type="hidden" name="NEW_ITEM-MATNR[1]" value="">
    <input type="hidden" name="NEW_ITEM-QUANTITY[1]" value="1">
    <input type="hidden" name="NEW_ITEM-UNIT[1]" value="">
    <input type="hidden" name="NEW_ITEM-PRICE[1]" value="988.01">
    <input type="hidden" name="NEW_ITEM-CURRENCY[1]" value="USD">
    <input type="hidden" name="NEW_ITEM-PRICEUNIT[1]" value="">
    <input type="hidden" name="NEW_ITEM-LONGTEXT_1:132[]" value="Sony VPL-SW225, 2600 ANSI lumens, 3LCD, WXGA (1280x800), 6000h, 210W, UHP">
    <input type="hidden" name="NEW_ITEM-VENDOR[1]" value="IQ">
    <input type="hidden" name="NEW_ITEM-VENDORMAT[1]" value="">
    <input type="hidden" name="NEW_ITEM-MANUFACTCODE[1]" value="Sony">
    <input type="hidden" name="NEW_ITEM-MANUFACTMAT[1]" value="VPL-SW225+TM-ST2">
    <input type="hidden" name="NEW_ITEM-EXT_PRODUCT_ID[1]" value="0027242869158">

Technically we re-use the product, basket product line item and/or customer information to display one or more products.


Decision: BasketLineitems which are either gifts or hidden gifts are not part of the OCI Punchout transfer format, since they would get added automatically when it comes to an order.

OCI Punchout Catalog Browsing

The Intershop Commerce Management allows to log onto a storefront as OCI Punchout user. Afterwards a reduced storefront (e.g., no footer, reduced header section, no checkout process) is available. An OCI Punchout user can still search or add products to a shopping cart, which can be transferred back to a referenced (procurement) system (see HOOK_URL).

Login URL

The OCI Punchout URL is publicly available, which any OCI Punchout user with valid credentials can access. The pattern of the URL is described below:


The following parameters are required for the default OCI Punchout storefront browsing:

USERNAMELogin name of a storefront user with the role OCI Punchout user
PASSWORDPassword of the OCI Punchout user
HOOK_URLTransfer the OCI Punchout data back to this URL. Usually a reference to the external (procurement) system.
<CUSTOM_NAME>optional; For customization purposes any additional URL parameter is stored in the storefront session and can be accessed later if required.

A short example is given below:


Additional Functions

Besides the OCI Punchout catalog browsing on the storefront there are several other specialized OCI Punchout functions available. Each function comes with their own parameters.

Product Details

Log into the storefront as OCI Punchout user and display product details in the OCI Punchout format for a given PRODUCTID.

Besides USERNAME, PASSWORD and HOOK_URL the following parameters must be provided.

FUNCTIONThis parameter must be set to DETAIL.
PRODUCTIDA unique product identifier as returned by the OCI Punchout transfer format



Validation of Products

The Validate function allows to retrieve up-to-date information for a specific product with a given quantity from the Intershop Commerce System. A possible use-case is the update of product data in external systems. The Intershop Commerce System returns a single (or no) product record in the OCI format which is automatically sent back to the caller's HOOK_URL.

Besides USERNAME, PASSWORD and HOOK_URL the following parameters must be provided.

FUNCTIONThis parameter must be set to VALIDATE.
PRODUCTIDA unique product identifier as returned by the OCI Punchout transfer format
optional; Defines the requested quantity. This setting may have influence on the returned price.
AUTOSUBMIToptional, This parameter is not part of the official specification. For testing issues AUTOSUBMIT can be set to false to suppress the automatic redirect to the provided HOOK_URL.



Internally the OCI Punchout Validate utilizes the cart (basket) functionality. This enables to have correct prices for a given quantity.

Background Search

The Background Search functionality can be utilized for cross-catalog searches of the procurement system. The search results are returned in an OCI conform format which is not sent automatically (as specified by the standard).

Besides USERNAME, PASSWORD and HOOK_URL the following parameters must be provided.

SEARCHSTRINGProvide a search term



Internally the OCI Punchout Background Search re-uses the standard product search which returns ProductBOs. Each product comes with a quantity of one. Opposite to the other functionalities no cart (basket) functionality is used. The values of the response are retrieved from the ProductBOs of the search result.


This function is not implemented.

Outbound Connection

For every outbound connection from the external system into the Intershop system a new basket is created. The lifetime of the basket is limited to the session. Therefore every OCI Punchout connection even with the same user creates a new session including an empty basket. Usually only a single OCI Punchout user per customer is configured, which is then used for multiple employees in the connected external system. A customer account administrator can configure a single OCI Punchout user. Utilizing the REST API, more than one OCI Punchout user can be configured.


The following artifacts are of interest when developing in the area of Punchout.


The following cartridges contain code artifacts:

bc_punchoutInterfaces for Punchout-related extensions, services and providers


Extensions and factories
app_sf_responsive_b2bOCI-Punchout-related functionality in the My Account section
app_sf_rest_b2bPunchout WebShop REST API
init_b2bRoles and permissions
demo_responsiveInitialize demo content (CMS) for OCI Punchout, and roles and permissions



Each customer may have his/her own Punchout users and Punchout field configuration.

Extension ID





Responsible for saving and retrieving the customer-specific configuration



Responsible for handling OCI users of the customer


Retrieve punchout conform values from a basket (cart) for a given product line item (PLI).

Extension ID





Responsible for getting the basket-related values based on the customer-specific Punchout configuration


Acquire Punchout conform values from a single product.

Extension ID





Responsible for getting the product-related values based on the customer-specific Punchout configuration

Roles and Permissions

For the OCI Punchout new roles and new permissions have been introduced.




The B2B OCI user.




The permission to manage Punchout settings. This permission is assigned to the role APP_B2B_ACCOUNT_OWNER.


The permission to view Punchout settings. This permission is assigned to the role APP_B2B_ACCOUNT_OWNER.


Permission to send the basket to the OCI backend. This permission is assigned to the new role APP_B2B_OCI_USER.

The Punchout user may have Punchout-standard-specific roles. Currently in the there is APP_B2B_OCI_USER set for the OCI Punchout.

The OCI user has limited access to storefront functionality like quotes. Therefore the storefront user's role is checked.


Some functionality is disabled on pages which are intended to be cached. To prevent page caching issues, a special user group is used. Other B2B user roles still do not own a dedicated user group.


A Punchout standard can be configured in the (see bc_punchout). The Punchout user roles and also individual fields can be specified per Punchout standard here.

Punchout Standard

Currently the Intershop Commerce System comes with the OCI Punchout standard. Each standard has a set of fields and user roles defined.

# e.g., punchout.configuration.standards=oci,<punchout-type>

Punchout-Specific User Roles

For the existing OCI Punchout standard the default Intershop Commerce System has the role APP_B2B_OCI_USER set for specific Punchout users.

# Define the users related to a given punchout type
# e.g., <punchout-standard>.users.roles=<my-custom-role>,<another-custom-role>

Punchout-Specific Fields

Per default the following fields are returned for the OCI Punchout standard. More fields may be added, but require their custom field configuration.


Field Configuration

The following set of properties has to be defined per Punchout standard (see <punchout-standard>) and per field (see <fieldId>).

Property Key



A comma-separated list of field IDs to be returned


The name of the field


The length of the value to be returned (-1 for unlimited length of the value to return)


True if the field can be configured by the customer


The transformation rule for retrieving the values


A formatter to be applied to the value

Custom Attributes Configuration

A new placeholder for product custom attributes has been created. The placeholder name for the transform configuration is simply the case sensitive name of the custom attribute (e.g.: {MyColor}). To control the access to the custom attributes of the product, the following property key has been introduced: <punchout-standard>.ver5.punchout.configuration.custom.attributes.with.access=MyColor,MySize. Only custom attributes with access will be resolved. All others are ignored.

The file is loaded by the configuration framework. This allows to overwrite the default Punchout configuration, e.g., in a custom cartridge.

Field Return Values

The return value of a Punchout field is determined by the transform value and the following formatter.


The transformation may contain constants and/or placeholders (e.g., "EN_{sku}"). Each placeholder is surrounded by curly brackets and returns a specific value. The return value of a placeholder is defined by a backing PunchoutPlaceholder implementation. The following standard placeholders are available:

  • Currency

  • Description

  • Discarded
  • ManufacturerName

  • ManufacturerSku

  • Price
  • ProductName

  • Quantity

  • Sku

  • SupplierName

  • SupplierSku

Using the placeholder Discarded prevents sending the field to the external system.

The placeholders are handled case-insensitive.

Transform (Handling of Custom Attributes)

A new placeholder has been implemented which now handles custom attributes. This placeholder does not show up in the list of available placeholders because it is used implicitly if no explicit placeholder name matches the list above.

There is now a new property key for custom attributes. This key contains a list of custom attribute names which can be accessed. The list of custom attribute names will automatically appended to the list of available placeholders in the UI. See Guide - B2B Storefront Functionality (valid from 7.10.17) | OCI_Punchout_Configuration for details and see the custom attributes configuration above for the required property configuration.

The placeholders for custom attributes are case-sensitive.


To apply a custom formatting to the by transform generated value, utilize formatters. The available formatters can be extended. The following standard formatters are available:

  • LowerCase

  • Trim

  • UpperCase

The formatters are handled case-sensitive. For adding new formatters and placeholders see Cookbook - OCI Punchout.


Mapping allows to convert the string resolved by a placeholder during the transformation step to another configurable value. The mapping configuration is stored with the customer only and not part of the properties described in section Field Configuration above. The mapping configuration of the map-from value allows a wildcard '*' to match any string. (e.g.: from: 210* - to: 2100000; a text like 21089365 gets mapped to 2100000). The mapping step happens between the transform with placeholders part and the formatter to do an upper case to strings for example. Details on how to configure the mapping is documented in Guide - B2B Storefront Functionality (valid from 7.10.17) | OCI_Punchout_Configuration.

Default Return Values

The following fields have a default return value specified by the property <punchout-standard>.ver5.punchout.configuration.<fieldId>.transform in


Persistent Data Structure

The Punchout configuration of a customer is stored in custom attributes. This allows it to easily import and export the configuration (see below).

Customer export XML
<?xml version="1.0" encoding="UTF-8"?>
<enfinity xmlns="" 
    xsi:schemaLocation=" b2b_customer.xsd dt.xsd" 
    major="6" minor="1" family="enfinity" branch="enterprise" build="build">
	<customer id="OilCorp">
		<company-name>Oil Corp</company-name>
		<description>Oil Corp is one of the world&amp;apos;s leading oil companies.</description>
			<custom-attribute name="oci.ver5.punchout.configuration.NEW_ITEM-UN2IT.formatter" dt:dt="string"></custom-attribute>
			<custom-attribute name="oci.ver5.punchout.configuration.NEW_ITEM-MATGROUP.transform" dt:dt="string">{ManufacturerName}</custom-attribute>
			<custom-attribute name="oci.ver5.punchout.configuration.NEW_ITEM-UNIT.formatter" dt:dt="string">uppercase</custom-attribute>
			<custom-attribute name="oci.ver5.punchout.configuration.NEW_ITEM-MATGROU2P.formatter" dt:dt="string">UpperCase</custom-attribute>
			<custom-attribute name="oci.ver5.punchout.configuration.NEW_ITEM-UN2IT.transform" dt:dt="string">box</custom-attribute>
			<custom-attribute name="oci.ver5.punchout.configuration.NEW_ITEM-MATGROUP.formatter" dt:dt="string">uppercase</custom-attribute>
			<custom-attribute name="oci.ver5.punchout.configuration.NEW_ITEM-UNIT.transform" dt:dt="string">{box}</custom-attribute>
			<custom-attribute name="oci.ver5.punchout.configuration.NEW_ITEM-MATGROU2P.transform" dt:dt="string">{ManufacturerName}</custom-attribute>


The Punchout configuration feature is implemented and documented as part of the Intershop documentation (Intershop B2B Frontend API | Punchout)

The following use-cases are supported:

  • Show list of Punchout standards
  • Show/create/delete Punchout users
  • Set Punchout user e-mail and password
  • Activate/deactivate single Punchout users
  • Set configurable fields for a Punchout standard
  • Retrieve available formatters/placeholders via OPTIONS call
  • Retrieve basket line item or product data using the customer-specific Punchout configuration


With the current implementation you should be aware of the following limitations:

  • A field is configured and afterwards the global configuration for this field is changed to NOT configurable: The customer's configuration might still work.
  • According to the OCI standard the BACKGROUND SEARCH returns unlimited results. This might lead to huge results even though it is internally limited to 99.999 items.
The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to if you experience login issues,
or if you want to register as customer.