> ## 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 stock level

> Make a voucher valid only for products whose traffic light status is green, yellow or red, and explain the rejection in the shop.

With this function, you tie a voucher to availability. It then applies only to products whose traffic light status matches a list you specify.

The practical benefit usually lies in clearing stock: a voucher that only works on green products steers demand towards what is plentiful in stock rather than towards what is already scarce.

## How the check works

The shop determines the current traffic light status for each basket item and compares it with your list. **One matching item is enough** for the voucher to be accepted. If none matches, the shop rejects it.

| Status | Meaning |
| - | - |
| `green` | Stock above the yellow threshold |
| `yellow` | Stock above the red threshold and up to the yellow threshold |
| `red` | Stock at or below the red threshold |

> [!WARNING]
>
> The status is calculated at the moment of redemption, not when the voucher is created. A voucher that still worked yesterday may be rejected today because the product has since dropped from green to yellow. Plan such promotions with a buffer from the threshold values.

> [!WARNING]
>
> If the shop is configured so that the ordered quantity affects the delivery status, a higher quantity shifts the status downwards. The same customer may then be able to redeem their voucher for one item but no longer for ten.

> [!NOTE]
>
> Products for which no traffic light status can be determined never meet the condition. A basket consisting entirely of such products always leads to rejection.

> [!NOTE]
>
> This filter does not recognize the finer gradations `red-hard` and `red-soft` that exist for display in the template. Only `red` counts here.

## 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: 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>InventoryState</t><setbehavior>asUnit</setbehavior><valueList>green,yellow</valueList></g>
```

In this example, the voucher applies to products with a green or yellow traffic light status.

| Bracket | Meaning |
| - | - |
| `<g>…</g>` | encloses the entire function |
| `<t>…</t>` | the type, here `InventoryState` |
| `<setbehavior>…</setbehavior>` | behavior for set products, optional |
| `<valueList>…</valueList>` | comma-separated list of permitted traffic light statuses from `green`, `yellow` and `red`, without spaces |

> [!WARNING]
>
> If `<valueList>` remains empty, the function is not active and the voucher applies without restriction. The shop does not report this. Anyone who meant to set the filter and makes a typo gives away the discount on the entire product range.

### 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 stock level, 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.

## Step 2: Add the error message

If no basket item matches the filter, the shop rejects the voucher with reason **22**. 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(22)}
   Dieser Gutschein gilt nur für Produkte mit bestimmter Verfügbarkeit
   und lässt sich auf Ihren Warenkorb nicht anwenden.<br>
   Bitte entfernen Sie den Gutschein oder legen Sie ein passendes Produkt in den Warenkorb.
{/MSG-Voucher_error(22)}
```

> [!WARNING]
>
> Word this text carefully. Unlike with a product-dependent voucher, the customer cannot see the condition, because the traffic light status is not shown everywhere in the shop. A hint as to which products are meant helps them more than a bare rejection.

Reference: MSG-Voucher\_error

## Step 3: Output the configuration in the template (optional)

For verification, you can display which stock levels an entered voucher is tied to.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{VOUCHER-SpecialFeatures_InventoryState}
   Dieser Gutschein ist an den Lagerbestand geknüpft.

   {VOUCHER-SpecialFeatures_InventoryState_ValueList}
      Gültig für Produkte mit folgendem Lagerbestand:
      ~VOUCHER-SpecialFeatures_InventoryState_ValueList~
   {/VOUCHER-SpecialFeatures_InventoryState_ValueList}

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

{/VOUCHER-SpecialFeatures_InventoryState}

{!VOUCHER-SpecialFeatures_InventoryState}
   Dieser Gutschein ist nicht an den Lagerbestand geknüpft.
{/!VOUCHER-SpecialFeatures_InventoryState}
```

> [!NOTE]
>
> As a standalone tag, `VOUCHER-SpecialFeatures_InventoryState_SetBehavior` outputs a number, `0` for `asUnit` and `1` for `single`. In the example, the query with a parameter translates the number into plain text so that the page does not show "Behavior for set products: 0".

> [!NOTE]
>
> `VOUCHER-SpecialFeatures_InventoryState_ValueList` outputs the list with a leading and trailing comma, i.e. `,green,yellow,`. This is how it is stored internally so that the shop can check for whole values. For display purposes, remove the outer commas.

Reference: VOUCHER-SpecialFeatures\_InventoryState · VOUCHER-SpecialFeatures\_InventoryState\_SetBehavior · VOUCHER-SpecialFeatures\_InventoryState\_ValueList

## Related topics

* Guide: Offering vouchers: Overview
* Guide: Creating or importing vouchers
* Guide: Providing voucher entry
* Guide: Vouchers depending on product data


## Related topics

- [Vouchers depending on product data](https://dokumentation.websale.de/en/v8s/gutscheine-anbieten/gutscheine-abhaengig-von-produktdaten.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)
- [Provide voucher entry](https://dokumentation.websale.de/en/v8s/gutscheine-anbieten/gutschein-eingabe-vorsehen.md)
- [Percentage vouchers](https://dokumentation.websale.de/en/v8s/gutscheine-anbieten/prozentuale-gutscheine.md)


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