META vouchers - WEBSALE Dokumentation

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.

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

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.

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.

{
   "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

The META code is looked up case-insensitively. A customer who enters sommer2026 therefore matches the entry SOMMER2026.

More than nine entries in vouchers have no effect. The shop processes the first nine and silently ignores the rest.

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.

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

<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

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.

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

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.

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

{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}

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.

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

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

​How redemption works

​The file meta_vouchers.json

​The settings in the shop configuration

​MetaVoucherErrorMode

​MetaVoucherShowAsBlock

​Extending the templates (optional)

​Related topics

How redemption works

The file `meta_vouchers.json`

The settings in the shop configuration

`MetaVoucherErrorMode`

`MetaVoucherShowAsBlock`

Extending the templates (optional)

Related topics