> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Vouchers depending on product data

> Make a voucher valid only for products that carry a specified value in a particular product data field, including free fields.

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.

> [!NOTE]
>
> 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.

> [!NOTE]
>
> 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`.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<AdditionalProductFieldsInBasket>
   +Field =    # technischer Name des Produktdatenfeldes
</AdditionalProductFieldsInBasket>
```

> [!WARNING]
>
> 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.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<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 |

> [!NOTE]
>
> 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.

> [!NOTE]
>
> 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.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<g><t>AdditionalProductFieldsFilterNegative</t><setbehavior>asUnit</setbehavior><filter><fieldname>Feldname</fieldname><valueInList>a,b,c</valueInList></filter></g>
```

> [!WARNING]
>
> 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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}
```

> [!WARNING]
>
> 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.

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

> [!NOTE]
>
> `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.

> [!NOTE]
>
> 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`.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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)}
```

> [!WARNING]
>
> 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

## Related topics

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


## Related topics

- [Vouchers depending on stock level](https://dokumentation.websale.de/en/v8s/gutscheine-anbieten/gutscheine-abhaengig-vom-lagerbestand.md)
- [VOUCHER- (Voucher)](https://dokumentation.websale.de/en/v8s/referenz/tags/voucher-gutschein.md)
- [Vouchers](https://dokumentation.websale.de/en/admin-interface/marketing/gutscheine.md)
- [Creating a purchase voucher product](https://dokumentation.websale.de/en/admin-interface/katalog/produkte/kaufgutschein-produkt.md)
- [Vouchers in the basket](https://dokumentation.websale.de/en/v8s/referenz/tags/basket/gutscheine-im-warenkorb.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.