Slevové kupóny a dárkové poukazy

Upraveno 2. listopadu 2026

Slevové kupóny a dárkové poukazy se zapínají pomocí elementu <voucher/>. V rámci tohoto elementu se pak zapínají a definují jednotlivé typy poukazů. Akci typu, jehož sekce (discountConfig, freeShippingConfig, giftConfig) v konfiguraci katalogu chybí, nelze založit ani přes REST API - vrací se chyba 400 s kódem voucher.type.notEnabled. Existující akce zůstávají editovatelné.

Konfigurační soubor se standardně nachází v adresáři config/module-edeeshop/features/benefit/voucher.xml.

Dokument dále popisuje:

Konfiguraci slevových poukazů
Konfiguraci poukazů pro dopravu zdarma
Konfiguraci dárkových poukazů
E-mail notifikace
Podpora pro odesílání slevových kódů pomocí newsletteru
Princip fungování dárkových poukazů

Příklad konfigurace

xml

1<voucher>2    <discountConfig>3        <maxUsagesPerOrder>1</maxUsagesPerOrder>4        <pricePolicyPriority>0</pricePolicyPriority>5        <roundings>6            <defaultRounding>0</defaultRounding>7            <rounding>8                <currency>EUR</currency>9                <rounding>2</rounding>10            </rounding>11        </roundings>12    </discountConfig>13    <freeShippingConfig>14        <maxUsagesPerOrder>1</maxUsagesPerOrder>15        <pricePolicyPriority>-500000</pricePolicyPriority>16    </freeShippingConfig>17    <giftConfig>18        <emailNotificationChunkSize>5</emailNotificationChunkSize>19        <maxUsagesPerOrder>50</maxUsagesPerOrder>20        <pricePolicyPriority>-2000000</pricePolicyPriority>21        <statusOfPreGeneratedCode>ACTIVE</statusOfPreGeneratedCode>22        <templateStoragePath>/eshop/giftVoucher/</templateStoragePath>23    </giftConfig>24    <catalogSpecific>25        <catalogCode/>26        <discountConfig>27            <maxUsagesPerOrder>1</maxUsagesPerOrder>28            <pricePolicyPriority>0</pricePolicyPriority>29            <roundings>30                <defaultRounding>0</defaultRounding>31                <rounding>32                    <currency>EUR</currency>33                    <rounding>2</rounding>34                </rounding>35            </roundings>36        </discountConfig>37        <freeShippingConfig>38            <maxUsagesPerOrder>1</maxUsagesPerOrder>39            <pricePolicyPriority>-500000</pricePolicyPriority>40        </freeShippingConfig>41        <giftConfig>42            <emailNotificationChunkSize>5</emailNotificationChunkSize>43            <maxUsagesPerOrder>50</maxUsagesPerOrder>44            <pricePolicyPriority>-2000000</pricePolicyPriority>45            <statusOfPreGeneratedCode>ACTIVE</statusOfPreGeneratedCode>46            <templateStoragePath>/eshop/giftVoucher/</templateStoragePath>47        </giftConfig>48    </catalogSpecific>49</voucher>50

Popis

voucher

Konfigurace kupónů - dárkových poukazů, slevových kupónů a kupónů na dopravu zdarma.

Vlastnosti této konfigurace lze specifikovat pro konkrétní katalog. Více zde.

Vlastnost	Popis	Hodnota	Povinná	Výchozí hodnota
discountConfig	Zapnutí a konfigurace slevových poukazů.	discountConfig	`-`	`-`
freeShippingConfig	Zapnutí a konfigurace poukazů pro dopravu zdarma.	freeShippingConfig	`-`	`-`
giftConfig	Zapnutí a konfigurace dárkových poukazů.	giftConfig	`-`	`-`
catalogSpecific	Vlastnosti této konfigurace lze specifikovat pro konkrétní katalog. Více zde.	`-`	`-`

discountConfig

Zapnutí a konfigurace slevových poukazů.

Vlastnost	Popis	Hodnota	Povinná	Výchozí hodnota
maxUsagesPerOrder	Maximální možný počet slevových kódů, který lze uplatnit v rámci jedné objednávky.	Integer	`-`	`1`
pricePolicyPriority	Priorita uplatnění dárkových poukazů v rámci všech cenových politik. Čím vyšší je priorita, tím dříve se politika uplatní. Default hodnota je `0`.	Long	`-`	`0`
roundings/defaultRounding	Zaokrouhlení procentuální slevy. Pokud není definováno, tak se použije globální hodnota definována v rámci konfigurace měn `currencyConfig`.	Integer	`-`	`-`
roundings/rounding	Zaokrouhlení procentuální slevy pro konkrétní měnu. Pokud není definováno použije se hodnota z `defaultRounding`.	List: roundings/rounding	`-`	`-`

roundings/rounding

Zaokrouhlení procentuální slevy pro konkrétní měnu.

Pokud není definováno použije se hodnota z defaultRounding.

Vlastnost	Popis	Hodnota	Povinná	Výchozí hodnota
currency	Kód měny (ISO 4217 - 3 znaky).	currency	`-`	`-`
rounding	Zaokrouhlení procentuální slevy.	Integer	`-`	`-`

freeShippingConfig

Zapnutí a konfigurace poukazů pro dopravu zdarma.

Vlastnost Popis Hodnota Povinná Výchozí hodnota

maxUsagesPerOrder

Maximální možný počet slevových kódů, který lze uplatnit v rámci jedné objednávky.

Integer

-

1

pricePolicyPriority

Priorita uplatnění poukazů na dopravu zdarma v rámci všech cenových politik.

Čím vyšší je priorita, tím dříve se politika uplatní.

Default hodnota je -500000.

Long

-

-500000

giftConfig

Zapnutí a konfigurace dárkových poukazů.

Vlastnost	Popis	Hodnota	Povinná	Výchozí hodnota
emailNotificationChunkSize	Maximální počet příloh s dárkovým poukazem v rámci jednoho emailu. Tedy pokud zákazník zakoupil více dárkových poukazů, než je tata hodnota, odešle se tolik notifikací, aby každá z nich obsahovala maximálně tento počet dárkových poukazů. Default hodnota je 5.	int	`-`	`5`
maxUsagesPerOrder	Maximální možný počet dárkový poukazů, který lze uplatnit v rámci jedné objednávky.	Integer	`-`	`50`
pricePolicyPriority	Priorita uplatnění dárkových poukazů v rámci všech cenových politik. Čím vyšší je priorita, tím dříve se politika uplatní. Default hodnota je `-2000000`.	Long	`-`	`-2000000`
statusOfPreGeneratedCode	Výchozí stav nových kódu dárkových poukazů, který jsou vytvářeny v AR. Pokud není definováno použije se `ACTIVE`.	`NOT_ACTIVATED` - V tomto stavu VoucherCode nelze použít. Jedná se o stav, který značí, že kod je v budoucnu použitelný, ale zatím nebyl aktivovaný. Nemůže tedy dojít ani k expiraci kódu vypočtené dle Voucher#getValidity(). Tento stav má tedy smysl pouze v případě, že je u akce vyplněna hodnota Voucher#getValidity(), kdy se pro kódy vypočítává čas expirace od doby aktivace. Z tohoto stavu lze přepnout do stavu ACTIVE a PRIVATE. `ACTIVE` - Je stav, kdy lze VoucherCode použít. Při prvním změně na tento stav se dopočítává platnost do pro daný kód (v případě vyplnění Voucher#getValidity()). Z tohoto stavu lze přepnout pouze do stavu PRIVATE. Jedná se o default stav, do kterého se generují nové kódy, pokud není definováno jinak ('getStatusOfNewCode'). `PRIVATE` - Je stav, kdy VoucherCode nelze použít. Lze přepnout do stavu ACTIVE.	`-`	`-`
templateStoragePath	Cesta ve storage (určené dle `storageId`), kam se budou ukládat šablony (PDF) pro dárkové poukazy. Default hodnota je `/eshop/giftVoucher/`.	String	`-`	`/eshop/giftVoucher/`

E-mail notifikace

V rámci tohoto rozšíření je možné odesílat notifikace o zakoupení dárkového poukazu.

Tyto notifikace se zapínají pomocí elementu <mailing>. Další nastavení mailingu je popsáno zde.

Příklad:

xml

1<voucher>2    <mailing/>3</voucher>

Podpora pro odesílání slevových kódů pomocí newsletteru

V rámci tohoto rozšíření je možné odesílat slevové kódy pomocí newsletteru, více informací zde.

Princip fungování dárkových poukazů

Vytvoření dárkových poukazů v AR

V sekci "Slevové kupóny" je nutné vytvořit novou akci pro dárkové poukazy.
Pro tuto akci je potřeba vytvořit produkt, jehož zakoupením se vygeneruje kód dárkového poukazu v rámci dané akce. Vazba mezi produktem a akcí se nastavuje při editaci akce. Produkt by měl mít nastavenou 0% sazbu DPH.
Jeden produkt může být spojen pouze s jednou akcí v rámci jedné měny, ale zároveň může být namapován na více akcí v různých měnách.

Doprava

Pro objednávky dárkových poukazů je standardně připraven typ dopravy "EMAIL". Aby se tato doprava zobrazovala správně, doporučuje se následující postup:

Vytvořit štítek "Dárkový poukaz" (nebo "Doprava e-mailem").
Tímto štítkem označit všechny produkty, které jsou napojené na dárkové poukazy, případně všechny produkty, které se doručují e-mailem místo fyzicky.
Vytvořit dopravu "E-mail" a v sekci "Povolit pouze pro produkty se štítkem" přidat vytvořený štítek "Dárkový poukaz". U všech ostatních doprav nastavit v sekci "Zakázat pouze pro produkty se štítkem" štítek "Dárkový poukaz".

Tento postup zajistí, že doprava "E-mail" bude nabízena pouze v případě, že objednávka obsahuje pouze dárkové poukazy. Naopak, pokud objednávka obsahuje i jiné produkty, budou nabízeny standardní typy dopravy.

Generování PDF

Pro každý dárkový poukaz lze vygenerovat PDF s poukazem. Šablona pro generování se nastavuje u konkrétní akce v administraci.
Data, která se do šablony předávají, jsou dostupná zde.
Pokud tato data nejsou dostatečná, je možné do Springu přidat vlastní implementaci VoucherGiftPdfDataBuilder.

Generování PDF je volitelné. Pokud šablona PDF není nastavena, kód dárkového poukazu je doručen pouze e-mailem.

Storno objednávky

Pokud je objednávka obsahující dárkové poukazy stornována, všechny vygenerované kódy se zneplatní (smažou z databáze).

Uplatnění dárkových poukazů

Dárkové poukazy lze uplatnit jako jedno-účelové poukazy nebo jako více-účelové poukazy. Způsob uplatnění se nastavuje v konfiguraci objednávek pod klíčem voucherTaxStrategy, kde je i popsán rozdíl mezi jedno-účelovým a více-účelovým poukazem. Cenová politika pro dárkové poukazy by měla být aplikována až na konci procesu zpracování objednávky.

Slevové kupóny a dárkové poukazy

Příklad konfiguraceZkopírovat odkaz na sekci

PopisZkopírovat odkaz na sekci

voucherZkopírovat odkaz na sekci

discountConfigZkopírovat odkaz na sekci

roundings/roundingZkopírovat odkaz na sekci

freeShippingConfigZkopírovat odkaz na sekci

giftConfigZkopírovat odkaz na sekci

E-mail notifikaceZkopírovat odkaz na sekci

Podpora pro odesílání slevových kódů pomocí newsletteruZkopírovat odkaz na sekci

Princip fungování dárkových poukazůZkopírovat odkaz na sekci

Vytvoření dárkových poukazů v ARZkopírovat odkaz na sekci

DopravaZkopírovat odkaz na sekci

Generování PDFZkopírovat odkaz na sekci

Storno objednávkyZkopírovat odkaz na sekci

Uplatnění dárkových poukazůZkopírovat odkaz na sekci