Insert codes

Insert codes are short codes that let you trace which advertising medium an order came from. Examples are a specific catalog, an advertisement, or a mailing. The code is appended to the product number, for example 123456-09. Here 123456 is the product number and 09 is the insert code. In the areas of configuration, templates, and interfaces, this concept has the technical name Insert. The related fields are named, for example, content.inserts (configuration), validInsertCodes (valid codes per product), and insert (code of an individual item). The table in the section Terms and technical names maps all the names to each other. The full technical details per layer (template module, configuration, REST and Storefront API) can be found on the detail pages linked under Related links.

The function is switched off by default. As long as it is not activated and set up (see Prerequisites), the shop behaves as before: no additional input fields, no additional displays, nothing is stored.

Prerequisites

For an insert code to take effect, three conditions must be met. If even one of them is missing, the function has no effect for the affected product. In this case, no error message appears.

The function is activated. In the configuration, content.inserts.enabled must be set to true. As long as it is off, no code is captured, resolved, or displayed.
The field assignment is set up (once per shop). The shop must know which product field contains the valid codes. This assignment is stored in content.usedFields.products.validInsertCodes. If it is missing, the shop cannot find the codes maintained on the product and treats every product as if it had no valid codes.
Valid codes are maintained on the product. Only when a product has specific codes in the validInsertCodes field can a code be applied to that product. If the list is empty, the default code (defaultInsertCode) is used, provided one is configured.

The concrete steps for this are described further below in the Setup section.

Without the field assignment (item 2), the product-specific codes have no effect. It is not enough to just create the product field and enter codes. If the assignment in usedFields.products is missing, each item silently gets the default code (or no code at all), even if codes are maintained on the products.

Terms and technical names at a glance

Depending on the layer (admin interface, configuration, template, or interface), the concept of insert codes has different names. This table maps the various designations to each other.

Concept	Admin Interface	Configuration	Template	Interface
Function active	`Settings -> Shop configuration -> Group "Insert code"`	`content.inserts.enabled`	`$wsInserts.enabled` or `$wsConfig.inserts.enabled`	`enabled` in `GET config/inserts`
Default code	`Settings -> Shop configuration -> Group "Insert code"`	`content.inserts.defaultInsertCode`	`$wsInserts.defaultInsertCode` or `$wsConfig.inserts.defaultInsertCode`	`defaultInsertCode` in `config/inserts`
Separator	`Settings -> Shop configuration -> Group "Insert code"`	`content.inserts.separator`	`$wsInserts.separator` or `$wsConfig.inserts.separator`	`separator` in `config/inserts`
Position (before/after)	`Settings -> Shop configuration -> Group "Insert code"`	`content.inserts.position`	`$wsInserts.position` or `$wsConfig.inserts.position`	`position` in `config/inserts`
Fixed code length (without separator)	`Settings -> Shop configuration -> Group "Insert code"`	`content.inserts.insertCodeLength`	—	—
Valid codes per product	Field “Valid insert codes” (details)	`validInsertCodes` (product field)	—	`custom.validInsertCodes` (Admin API)
Field assignment (once)	—	`usedFields.products.validInsertCodes`	—	—
Remembered code per product	—	—	`$wsInserts.byProduct[<product ID>]`	—
Code per basket item	—	—	`$item.insert`	`insert` (add / update / response)
Item number of the item	—	—	`$item.itemNumber`	`itemNumber` (response)
Item number including code	—	—	Component `components/itemNumberWithInsert.htm`	Compose from `itemNumber` and `insert`
Pass code via URL	—	—	—	URL parameter `insert`

In the stored order data of an item, the code is in the insert field and the item number is in the itemNumber field. The latter contains the number of the main product, even if a variant was ordered. The exact field names per interface can be found on the respective detail pages (see Related links).

How the shop determines an insert code

If the prerequisites are met, when a product is added to the basket the shop determines the insert code for that item in the following order:

A valid code has been provided → The code is applied to the product.
No code has been provided → The shop applies the code it previously remembered for exactly this product (see Remembered insert code per product), provided it is valid for the product. For variants, the specific variant counts.
Otherwise → The default code (defaultInsertCode) stored in the configuration is used. If none is stored, the item remains without a code.

The three cases build on each other. Case 3 only applies if no code was provided and no matching code is stored for this product. So “no code → default code” is not an absolute rule but the last step in the chain.

Remembered insert code per product

The shop remembers a detected insert code for the product on which it was captured. For variants, this applies to the specific variant. The shop does not transfer the code to other products.

Each basket item keeps its own code. This is why several products with different codes can be in the basket.
The remembered code is retained for this product during navigation, for example on the product detail page, when switching variants, and in the basket. This also applies if the product is removed from the basket in the meantime.
Two variants of the same product each keep their own code.
If the same product is added again in the same variant, no second item is created. The quantities are added up. However, if adding it again brings a code with it, the item receives the newly determined code. Without a code, the item keeps its previous one.
Every detected code is remembered, including an invalid one. It replaces the previously remembered code of this product. The next time the product is added without a code, the default code is then used, provided one is configured.
The remembered codes only apply to the current session. After the order is completed, a new session begins, so they are dropped. In addition, the shop resets them when it empties the basket on logout or when switching customer accounts.

The remembered code is available in the template via the $wsInserts module. This lets you display it wherever a product is shown, for example on category tiles and the product detail page.

What does “valid code” mean

Which codes are allowed for a product is determined by product maintenance. The check is character-exact and case-sensitive. For example, DA and da are not the same.

Storage in the order

The determined insert code is stored with the order and is therefore available in the order evaluation as a dedicated piece of information.

Where a code can be entered

There are three independent ways in which an insert code can reach the shop.

Via the URL: An insert code can be appended to a product call via the insert URL parameter. This is suitable for links from catalogs, advertisements, or mailings. There are two independent ways to do this:
- on a technical view URL using the product ID: ?view=Product&productId=<productId>&insert=<code>
- on a SEO URL of the product: /colorful-t-shirt?insert=<code>
Direct order: The customer enters the item number together with the insert code in a single field, exactly as printed in the catalog, for example 123456/AB. The shop splits off the code itself. How this works is described under Enter insert codes in the direct order.
Basket (interface): When adding or updating an item, the code can be passed directly, see Storefront API basket.

A view URL here is a technical shop URL generated via the template function $wsViews.url(...) or $wsViews.viewUrl(...) (in contrast to the human-readable SEO URL). For details see Module $wsViews. Both URL types accept the insert parameter equally.

If a product is called without the insert parameter, an insert code already remembered for this product is retained. “No parameter” is therefore not treated the same as “no code”. The remembered code is only applied when the product is added to the basket and is checked there against the valid codes.

Practical example: from advertisement to order

The following scenario illustrates how the rules interact: A customer receives a mailing with a product link to which the insert code 09 is appended (for example /colorful-t-shirt?insert=09). With one click, they land on the product page. The shop remembers the code 09 for the T-shirt. Then they add the T-shirt to the basket. Since 09 is a valid code for this product, the item carries the code and the item number appears as 123456-09. They then keep browsing, add a pair of trousers to the basket, and do not open a code link in the process. The code 09 belongs to the T-shirt and is not transferred to the trousers. For the trousers, either the default code applies or the item remains without a code. Later, they open a jacket with the code DA via a second link from an advertisement and add it to the basket. The basket now contains three items: the T-shirt with the code 09, the trousers without a code, and the jacket with the code DA. When the order is completed, the code of each item is stored together with the order. Afterwards, a new session begins and the remembered codes are dropped.

In the order history, the stored code is present in the order data (in the insert field). The shop does not provide a fully assembled display of item number and code there or in the basket. How to display the code in the order history is described under Examples → Order history.

Special cases

Set items: The code is resolved both for the main item and for the contained sub-items. Each sub-item checks the code against its own valid codes (otherwise the default code applies). This works just like a separately added item. Variants: The valid codes are maintained at the main product level and apply to all its variants. The code, however, is remembered per variant. If the customer switches the variant on the product detail page, the new variant’s own previously stored code applies. The shop does not take over the code of the previously selected variant. The code is always checked against the valid codes of the main product.

Setup

This section describes the concrete steps for the conditions listed under Prerequisites.

Configuration

The settings are located in the configuration area under Einstellungen -> Shop-Konfiguration -> Gruppe „Werbemittelkennzeichen" (content.inserts):

Setting	Meaning	Default
`enabled`	Switches the entire function on or off.	off
`defaultInsertCode`	Used when no code or an invalid code has been entered. Leave empty if no code should be set in that case.	empty
`separator`	Character between the product number and the code, for example `-`.	`-`
`position`	Whether the code appears after the product number (`123456-09`) or before it (`09-123456`).	after
`insertCodeLength`	Fixed number of characters of the insert code. Only needed if no separator is set. In that case, number and code can only be separated in the direct order using the fixed length. If a separator is set, the value has no meaning.	`0`

As long as enabled is switched off, the function has no effect anywhere in the shop, regardless of how individual products are maintained.

If the shop works without a separator using insertCodeLength, all insert codes in the shop must have the same length. A code with a different length is split off incorrectly in the direct order.

Note on defaultInsertCode: The default code applies across all products for every entry that cannot be resolved to a valid code. If you set the code to a fixed value, keep in mind that this value can then also be used for items that are actually not intended to have an insert code. When in doubt, leave the value empty.

Create the product field

If the validInsertCodes field does not yet exist in the shop, it is created once as a custom product field. In the admin interface, this is done in the Catalog → Products area via the product field settings (select Settings / gear icon at the top right). The table there shows all existing product fields with name, type, and maximum length. Using the New button, the field is created with the following settings:

Setting	Value
Name	`validInsertCodes`
Label	Valid insert codes
Type	List (text entries)
Maximum length	16 characters per entry

Alternatively, the field can be created via the REST API configuration in the content.customProductField node.

Set up the field assignment

After creating the product field, it must be assigned to the function once. Only through this assignment does the shop know in which product field the valid insert codes are stored. The assignment is maintained in the configuration node content.usedFields. In the products area, the validInsertCodes entry points to the created product field:

{
  "products": {
    "validInsertCodes": "content.customProductField.validInsertCodes"
  }
}

The example shows only the relevant entry. The node also contains the assignments of all other functional areas (for example weight, crossSelling, metaTitle). These existing entries are retained unchanged; only the value of validInsertCodes is set.

Without this assignment, the codes maintained on the product have no effect. The shop cannot then determine the valid codes of a product, and each item silently receives the default code or remains without a code, even if codes are maintained on the products. So it is not enough to just create the product field — it must also be assigned.

Valid codes on the product

The custom product field “Valid insert codes” (validInsertCodes) is maintained in the admin interface on the detail page of the respective product. Like every custom field, it appears in the corresponding field group. Otherwise, it appears in the catch-all group “Other”. This field determines per product which codes are allowed for that product. It is a list field. Each valid code is entered as a separate entry. A separator is not needed and the codes are not maintained as a single continuous string. The following requirements apply when adding a code:

Each entry may be a maximum of 16 characters long.
Each code is its own list entry. Codes are not strung together in one field using commas or other separators.
Codes are case-sensitive (for example, DA is not the same as da).
The field is maintained at the main product level and also applies to its variants.
If the list is empty, no code can be applied for that product (at most the default code applies, if set).

In the template, the field is available as a list, for example via $cProduct.custom.validInsertCodes on the product page or $item.product.custom.validInsertCodes on the basket item. Output is done via a loop or with join and a freely chosen separator:

{{= $cProduct.custom.validInsertCodes | join(", ") }}

Result
The valid codes of the product are displayed comma-separated, for example DA, 09.

Display in the shop

The insert code can be displayed as part of the item number in the basket, in the order overview, in the confirmation email, in the order PDF, and in the order history (for example 123456-09). The configured order and the configured separator apply. The prerequisite is that the output is embedded in the respective template (see Examples). The display is composed of the item number of the item ($item.itemNumber) and the code ($item.insert). For variants, $item.itemNumber corresponds to the number of the ordered variant. The reusable component components/itemNumberWithInsert.htm is available for composing the display. Depending on the configuration, it outputs Code<separator>Number or Number<separator>Code. If the code is empty, it outputs only the number. Using the $wsInserts module, a remembered code can also be displayed outside the basket, for example on category tiles and the product detail page. If an unknown code is entered, the shop discards it and, if configured, falls back to the default value. As a result, the order is never blocked.

Modules

The following modules are used for outputting the insert code in the template:

$wsInserts provides the code remembered per product via $wsInserts.byProduct as well as the settings (active, separator, position, default code). This lets you display the code wherever a product is shown.
$wsBasket provides, per basket item, the code via $item.insert and the item number of the item via $item.itemNumber.
$wsConfig provides the same settings as $wsInserts via $wsConfig.inserts. The object remains available.

Capturing a code (URL, direct order, basket interface) does not require its own module. It happens via URL parameters, the direct order form, or the Storefront API.

Examples

Output the item number with insert code

In the basket (and analogously in the order overview, the email, and the PDF), pass the item number and the code of the item to the components/itemNumberWithInsert.htm component. The component itself takes care of the order and the separators.

{{ foreach $item in $wsBasket.items }}
  <p>Item no.: {{ include "components/itemNumberWithInsert.htm" with $cNumber = $item.itemNumber, $cCode = $item.insert }}</p>
  <p>Product name: {{= $item.product.name }}</p>
{{ /foreach }}

Result
Each item shows its item number including the insert code, if one has been captured. Otherwise, the plain item number is displayed.

Display the remembered insert code on the product

On a category tile or the product detail page, $wsInserts.byProduct provides the code remembered for the product. If no valid code is remembered for the product, the value remains empty.

{{ if $wsInserts.enabled and $wsInserts.byProduct[$cProduct.id] }}
  <p>Item no.: {{ include "components/itemNumberWithInsert.htm" with $cNumber = $cProduct.itemNumber, $cCode = $wsInserts.byProduct[$cProduct.id] }}</p>
{{ /if }}

Result
If the customer opened the product via a link with an insert code, the item number appears with this code. Otherwise, nothing appears.

Output the insert code as a separate field

If the plain code should also appear as its own field, first check whether the function is active. Otherwise nothing will appear when the function is switched off.

{{ if $wsConfig.inserts.enabled }}
  {{ foreach $item in $wsBasket.items }}
    {{ if $item.insert }}
      <p>Insert code: {{= $item.insert }}</p>
    {{ /if }}
  {{ /foreach }}
{{ /if }}

Result
The insert code appears only when the function is active and only for items that carry a code.

Enter insert codes in the direct order

On the direct order page (template modules/directOrder.htm, module $wsDirectOrder), customers can enter item numbers row by row. A separate input field for the insert code is not required. The customer enters the item number together with the code in the existing item number field, exactly as printed in the catalog. The shop splits off the code based on the configuration:

Configuration	Input	Item number	Code
Separator `/`, position after	`123456/AB`	`123456`	`AB`
Separator `/`, position before	`AB/123456`	`123456`	`AB`
No separator, `insertCodeLength` `2`, position before	`AB123456`	`123456`	`AB`
No separator, `insertCodeLength` `2`, position after	`123456AB`	`123456`	`AB`

The shop proceeds in this order:

It checks whether the entire input is a valid item number. If so, it does not split anything off. This way, a real item number that happens to contain the separator is not cut apart.
Otherwise, it splits off the code and checks the remaining number. If the code comes after, the shop splits at the last separator. If it comes before, the shop splits at the first separator. The number 123-456-09 with the separator “-” therefore becomes the number 123-456 with the code 09.
The split-off code is checked against the valid codes of the product found, as described under How the shop determines an insert code.

Inputs without a code work unchanged, which means item number, product ID, EAN, or ISBN can still be used. So that customers know they can enter the code, the item number field can receive a corresponding hint. In the following example, the placeholder is only extended when the function is active:

<input type="text"
       name="id"
       class="form-control"
       placeholder="Item number{{ if $wsInserts.enabled }} with insert code{{ /if }}"
       ...>

Result
When the function is active, the placeholder reads “Item number with insert code”. If the customer enters, for example, the number 123456/AB, the shop captures the product with the number 123456 and the code AB in the order form. The code is then available in $wsDirectOrder.items[…].insert. The item only reaches the basket with the separate form that transfers the captured items via the BasketItemAdd action. So that the code is retained in the process, the form additionally sends the field multiProducts.<productNumber>.insert for each item. A complete example can be found under Transfer items to the basket.

Order history

The order history does not work with the basket but with the stored order data ($order.orderList.item). There, too, the template composes the display itself. The components/itemNumberWithInsert.htm component is also suitable for this; pass it the item number (itemNumber) and the stored code (insert) of the order item. Note that itemNumber in the order data is the number of the main product, even for ordered variants.

$wsInserts: code remembered per product via $wsInserts.byProduct as well as the settings (active, separator, position, default code).
$wsConfig: settings via $wsConfig.inserts (active, separator, position, default code).
$wsBasket: output per item via $item.insert and $item.itemNumber.
$wsViews: generating view URLs (url(), viewUrl()), to which the insert parameter can be appended.
content - Catalog: configuration block content.inserts and the mandatory field assignment usedFields.products.
API reference Products: maintaining the valid codes per product (custom.validInsertCodes). Requires the field assignment usedFields.products (see Prerequisites).
API reference Configuration: maintaining the configuration block content.inserts via the configuration node endpoints.
Storefront API basket: setting and reading the code via the insert field as well as GET /api/v1/config/inserts.

Frontend

The basics

Getting started

Feature overview

Examples

Reference – Actions

Reference – Language

Reference – Modules

Prerequisites

Terms and technical names at a glance

How the shop determines an insert code

Remembered insert code per product

What does “valid code” mean

Storage in the order

Where a code can be entered

Practical example: from advertisement to order

Special cases

Setup

Configuration

Create the product field

Set up the field assignment

Valid codes on the product

Display in the shop

Modules

Examples

Output the item number with insert code

Display the remembered insert code on the product

Output the insert code as a separate field

Enter insert codes in the direct order

Order history

​Prerequisites

​Terms and technical names at a glance

​How the shop determines an insert code

​Remembered insert code per product

​What does “valid code” mean

​Storage in the order

​Where a code can be entered

​Practical example: from advertisement to order

​Special cases

​Setup

​Configuration

​Create the product field

​Set up the field assignment

​Valid codes on the product

​Display in the shop

​Modules

​Examples

​Output the item number with insert code

​Display the remembered insert code on the product

​Output the insert code as a separate field

​Enter insert codes in the direct order

​Order history

​Related links

Prerequisites

Terms and technical names at a glance

How the shop determines an insert code

Remembered insert code per product

What does “valid code” mean

Storage in the order

Where a code can be entered

Practical example: from advertisement to order

Special cases

Setup

Configuration

Create the product field

Set up the field assignment

Valid codes on the product

Display in the shop

Modules

Examples

Output the item number with insert code

Display the remembered insert code on the product

Output the insert code as a separate field

Enter insert codes in the direct order

Order history

Related links