Vouchers depending on product data - WEBSALE Dokumentation

You can restrict a voucher to certain products without listing every single product number. Instead, the shop checks a product data field: if the product carries one of the specified values there, the voucher applies to it. Free product data fields can be used as well. This lets you tie promotions to attributes that are maintained anyway, for example a brand, a season or a sustainability label.

How the check works

The shop goes through the basket and checks each item against the stored filters. One matching item is enough for the voucher to be accepted. If not a single item matches, the shop rejects it.

Multiple filters are combined with OR. A voucher with two filters therefore applies as soon as one basket item meets either of them. An AND combination can only be achieved via a single field with suitably prepared values.

Prerequisite

The voucher generator must be activated. Contact your WEBSALE representative to arrange this.

If the vouchers come from an external system and are therefore not in WEBSALE format, add the entry ExternalVouchers-Allow = yes in the <Voucher-Txt> section of the shop.config.

Guide: Providing voucher entry · Reference: Voucher-Txt section

Step 1: Pass the product data field to the basket

The shop only checks fields that are actually available in the basket. Therefore, enter the desired field in the shop.config.

<AdditionalProductFieldsInBasket>
   +Field =    # technischer Name des Produktdatenfeldes
</AdditionalProductFieldsInBasket>

Without this entry, the basket does not know the field and the filter never finds a match. The voucher is then rejected for every basket, even though the voucher configuration is not wrong. This is the most likely reason when such a voucher “simply doesn’t work”.

Reference: AdditionalProductFieldsInBasket section

Step 2: Create the filter in the voucher

When creating the voucher in the voucher generator, enter a string following the scheme below in the Kundenspezifische Features (custom features) field at the very bottom.

<g><t>AdditionalProductFieldsFilter</t><setbehavior>asUnit</setbehavior><filter><fieldname>Feldname</fieldname><valueInList>a,b,c</valueInList></filter></g>

Bracket	Meaning
`<g>…</g>`	encloses the entire function
`<t>…</t>`	the type, here `AdditionalProductFieldsFilter`
`<setbehavior>…</setbehavior>`	behavior for set products, optional
`<filter>…</filter>`	a condition. Can be used multiple times
`<fieldname>…</fieldname>`	the technical name of the product data field
`<valueInList>…</valueInList>`	comma-separated list of permitted values, without spaces

Behavior for set products

Value	Effect
`asUnit`	Set sub-products are treated as a unit; the set parent product is checked. The voucher applies to the entire set or to none of its parts. Default
`single`	Set sub-products are checked individually. Depending on the product data, the voucher then applies to all, some or none of the parts of the set

Only the value single is evaluated. Any other value and an empty entry mean asUnit. A typo in single therefore silently results in unit behavior.

The total length of the string is limited to 1000 characters. Multiple <filter> brackets can be specified one after another in the same <g> group and are combined with OR.

The inverse variant

In addition to the filter described, the shop also supports the same structure as an exclusion. To use it, enter AdditionalProductFieldsFilterNegative as the type; everything else stays the same.

<g><t>AdditionalProductFieldsFilterNegative</t><setbehavior>asUnit</setbehavior><filter><fieldname>Feldname</fieldname><valueInList>a,b,c</valueInList></filter></g>

The inverse variant has its own tag family with the suffix Negative, but no separate documentation. Test its behavior in a test shop before using it in a promotion.

Step 3: Output the configuration in the template

For verification, you can display which checks are attached to an entered voucher.

{VOUCHER-SpecialFeatures_AddProdFieldsFilter}
   Dieser Gutschein ist an Produktdaten geknüpft.
   Konfigurierte Prüfungen: ~VOUCHER-SpecialFeatures_AddProdFieldsFilter_Filter~

   Verhalten bei Setprodukten:
   {VOUCHER-SpecialFeatures_AddProdFieldsFilter_SetBehavior(0)}Set als Einheit{/VOUCHER-SpecialFeatures_AddProdFieldsFilter_SetBehavior(0)}
   {VOUCHER-SpecialFeatures_AddProdFieldsFilter_SetBehavior(1)}Set-Unterprodukte einzeln{/VOUCHER-SpecialFeatures_AddProdFieldsFilter_SetBehavior(1)}

   {@VOUCHER-SpecialFeatures_AddProdFieldsFilter_Filter}
      Feldname: ~VOUCHER-SpecialFeatures_AddProdFieldsFilter_Filter_FieldName~<br>
      Zulässige Werte: ~VOUCHER-SpecialFeatures_AddProdFieldsFilter_Filter_ValueInList~<br>
   {/@VOUCHER-SpecialFeatures_AddProdFieldsFilter_Filter}

{/VOUCHER-SpecialFeatures_AddProdFieldsFilter}

{!VOUCHER-SpecialFeatures_AddProdFieldsFilter}
   Dieser Gutschein ist nicht an Produktdaten geknüpft.
{/!VOUCHER-SpecialFeatures_AddProdFieldsFilter}

As a standalone tag, VOUCHER-SpecialFeatures_AddProdFieldsFilter_SetBehavior outputs a number, 0 for asUnit and 1 for single, not the text. If you place the tag directly after a label, the page shows “Behavior for set products: 0”. In the example above, the query with a parameter translates the number into plain text.

The set behavior applies to the whole group, not per filter. It therefore belongs before the loop, not inside it.

VOUCHER-SpecialFeatures_AddProdFieldsFilter_Filter_ValueInList outputs the list of values with a leading and trailing comma, i.e. ,a,b,c,. This is how it is stored internally so that the shop can reliably check for whole values. For display purposes, remove the outer commas.

The same tag pattern exists for the inverse variant, with AddProdFieldsFilterNegative instead of AddProdFieldsFilter.

Reference: VOUCHER-SpecialFeatures_AddProdFieldsFilter · VOUCHER-SpecialFeatures_AddProdFieldsFilter_SetBehavior · VOUCHER-SpecialFeatures_AddProdFieldsFilter_Filter · VOUCHER-SpecialFeatures_AddProdFieldsFilter_Filter_FieldName · VOUCHER-SpecialFeatures_AddProdFieldsFilter_Filter_ValueInList

Step 4: Add the error message

If no basket item matches the filter, the shop rejects the voucher with reason 21. Add this reason wherever you have integrated the voucher entry, i.e. on the basket page ws_basket.htm or the order overview page ws_place_order.htm.

{MSG-Voucher_error(21)}
   Dieser Gutschein gilt nicht für die Produkte in Ihrem Warenkorb.<br>
   Bitte entfernen Sie den Gutschein oder legen Sie ein passendes Produkt in den Warenkorb.
{/MSG-Voucher_error(21)}

Without this text, the customer sees an empty message and does not know why their code was rejected. For product-dependent vouchers in particular, this is by far the most common rejection.

Reference: MSG-Voucher_error

Guide: Offering vouchers: Overview
Guide: Creating or importing vouchers
Guide: Providing voucher entry
Guide: Vouchers depending on stock level

​How the check works

​Prerequisite

​Step 1: Pass the product data field to the basket

​Step 2: Create the filter in the voucher

​Behavior for set products

​The inverse variant

​Step 3: Output the configuration in the template

​Step 4: Add the error message

​Related topics

How the check works

Prerequisite

Step 1: Pass the product data field to the basket

Step 2: Create the filter in the voucher

Behavior for set products

The inverse variant

Step 3: Output the configuration in the template

Step 4: Add the error message

Related topics