> ## 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.

# META vouchers

> Bundle several voucher codes behind a collective code, maintain the mapping in a JSON file and define the behavior for faulty sub-vouchers.

A META voucher is a collective code. The customer enters a single number, and in the background the shop redeems several stored vouchers at once. This is useful when a promotion consists of several components, for example ten percent off together with free shipping, but the customer should only have to remember one code.

The mapping is not stored in the voucher generator but in a file that you maintain yourself.

> [!NOTE]
>
> This function does not need to be activated.

## How redemption works

| Step | What happens |
| - | - |
| The customer enters the META code | The shop looks it up in the file `meta_vouchers.json` |
| Code found | The shop redeems the stored sub-vouchers one after another |
| A sub-code is already in the basket | It is skipped, without an error message |
| A sub-voucher is invalid | `MetaVoucherErrorMode` determines what happens next |

> [!WARNING]
>
> Only **one** META voucher can be redeemed at a time. As long as a voucher from a META code is in the basket, a second META code is not recognized and is treated like an unknown number.

> [!NOTE]
>
> The sub-vouchers occupy the same slots as multiple redeemed vouchers. This results in the upper limit of nine sub-vouchers per META code.

Guide: Redeeming multiple vouchers

## The file `meta_vouchers.json`

Create the file manually in the shop's configuration directory, i.e. in the directory that applies to all subshops. It contains one entry per META code.

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
   "SOMMER2026": {
      "vouchers": ["RABATT10", "VERSANDFREI"],
      "showAsBlock": true
   },
   "WILLKOMMEN": {
      "vouchers": ["NEUKUNDE5", "GRATISPROBE", "VERSANDFREI"]
   }
}
```

| Field | Meaning |
| - | - |
| Key | the code the customer enters |
| `vouchers` | list of sub-voucher codes to be redeemed |
| `showAsBlock` | optional, controls block handling for this META code. If not specified, the setting from the `shop.config` applies |

> [!NOTE]
>
> The META code is looked up case-insensitively. A customer who enters `sommer2026` therefore matches the entry `SOMMER2026`.

> [!WARNING]
>
> More than nine entries in `vouchers` have no effect. The shop processes the first nine and silently ignores the rest.

> [!WARNING]
>
> `showAsBlock` must be a real JSON boolean, i.e. `true` or `false` without quotation marks. The notation `"true"` is ignored, and the default from the configuration applies.

> [!WARNING]
>
> If the file is missing, the entered code is simply treated as unknown. If it exists but is malformed, the shop logs an error but behaves the same way externally. A META code that is not recognized is therefore first of all a reason to check the file.

## The settings in the shop configuration

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<Voucher-Txt>
   MetaVoucherErrorMode   = reject-all
   MetaVoucherShowAsBlock = yes
</Voucher-Txt>
```

### `MetaVoucherErrorMode`

| Value | Behavior for an invalid sub-voucher |
| - | - |
| `reject-all` | The entire META voucher is rejected; sub-vouchers already redeemed are removed again. Default |
| `accept-valid` | The invalid sub-voucher is skipped; the others remain redeemed |

> [!NOTE]
>
> `reject-all` is the default, and any unrecognized value also leads to it. It is the more honest option: the customer either gets the whole package or nothing at all, and is not puzzled by a partial discount.

> [!NOTE]
>
> With `accept-valid`, the shop only suppresses the error message if at least one sub-voucher has already been redeemed successfully. If the very first one fails, the customer sees its error message, even if the following sub-vouchers take effect.

### `MetaVoucherShowAsBlock`

| Value | Behavior |
| - | - |
| `yes` | The sub-vouchers are treated as a block. Clicking delete removes all of them at once. Default |
| `no` | Each sub-voucher can be deleted individually |

> [!NOTE]
>
> With `no`, the shop keeps count during deletion. Once the last sub-voucher has been removed, it also resets the META data, and the customer can enter a different META code.

> [!NOTE]
>
> The setting in the file overrides the setting in the configuration. This allows a single promotion to be handled differently without changing the default for all others.

Reference: Voucher-Txt section

## Extending the templates (optional)

Four tags make it visible in the template that a voucher originates from a META code.

| Tag | Content |
| - | - |
| `VOUCHER-IsFromMeta` | section that only applies to a voucher from a META code |
| `VOUCHER-MetaCode` | the META code entered |
| `VOUCHER-MetaSubCount` | number of successfully redeemed sub-vouchers |
| `VOUCHER-MetaShowAsBlock` | section that applies when block handling is active |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{VOUCHER-Number}

   Gutscheinnummer: ~VOUCHER-Number~

   {VOUCHER-IsFromMeta}
      Teil der Aktion ~VOUCHER-MetaCode~
      {VOUCHER-MetaSubCount}
         mit insgesamt ~VOUCHER-MetaSubCount~ Gutscheinen
      {/VOUCHER-MetaSubCount}

      {VOUCHER-MetaShowAsBlock}
         Diese Gutscheine gehören zusammen. Wenn Sie einen davon entfernen,
         werden alle entfernt.
      {/VOUCHER-MetaShowAsBlock}
   {/VOUCHER-IsFromMeta}

   <input type="submit" name="~BT-Voucher_delete~" value="Gutschein entfernen">

{/VOUCHER-Number}
```

> [!WARNING]
>
> The notice about block handling is not a mere extra. Without it, the customer clicks delete to get rid of a single voucher and loses the entire promotion. If you leave `MetaVoucherShowAsBlock` set to `yes`, say so.

> [!NOTE]
>
> The tags are also available inside the loop over the additional vouchers. With multiple redeemed vouchers, you therefore need the block in both places: outside the loop for the first voucher and inside it for the others.

Reference: VOUCHER-MetaCode · VOUCHER-MetaSubCount · VOUCHER-IsFromMeta · VOUCHER-MetaShowAsBlock · VOUCHER-MultiVoucher

## Related topics

* Guide: Offering vouchers: Overview
* Guide: Providing voucher entry
* Guide: Redeeming multiple vouchers


## Related topics

- [Prices, taxes, and currency](https://dokumentation.websale.de/en/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/preise-steuern-und-waehrung.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)
- [Voucher](https://dokumentation.websale.de/en/frontend/referenz/aktionen/voucher.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.