> ## 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. # Purchase vouchers for printing > Sell vouchers as a product, display the number immediately after payment, and provide the voucher as a PDF for printing. A purchase voucher is a voucher that the customer buys in the shop, usually to give as a gift. Its biggest advantage is speed: the buyer downloads it immediately after payment and prints it out, which makes it a useful last-minute gift. Technically, a purchase voucher is a completely ordinary product. It is added to the basket, goes through the normal ordering process, and is paid for like any other product. The special part happens in the background. ![Kaufgutschein](https://mintcdn.com/websaleag-44ee7ea6/Vx3oBE97Leuacjk4/images/kaufgutschein.jpg?fit=max\&auto=format\&n=Vx3oBE97Leuacjk4\&q=85\&s=e3a5c173a5950f3c98ffda29ff3ac39d) ## What the process looks like | Step | What happens | | - | - | | The customer adds the voucher product to the basket | The shop generates a voucher number or takes it from a previously created pool | | The customer pays | The voucher number is displayed to them immediately | | The customer downloads the voucher | For each voucher number, a PDF file with number, amount, and validity is created from a dedicated template | > [!NOTE] > > Because the buyer sees the number immediately after payment and can redeem it right away, purchase vouchers can be tied to secure payment methods. How to set this up is described in step 5. > [!NOTE] > > If the customer changes the value after adding it to the basket, for example via a different variant, the shop draws the numbers again. The number that ends up on the voucher is therefore only final with the order. Use case: Offer purchase vouchers for printing with multiple designs ## The integration ### Step 1: Activation If you want to use the voucher generator, it must be activated for your shop. Contact your WEBSALE representative to do so. > [!NOTE] > > If the vouchers come from an external system and are therefore not in WEBSALE format, add the entry `ExternalVouchers-Allow = yes` in the `` section of the `shop.config`. ### Step 2: Integrating voucher entry If your shop does not offer vouchers at all yet, the option to enter them is missing. Without it, nobody can redeem the purchased voucher later. Guide: Provide voucher entry ### Step 3: Creating the purchase vouchers as products Purchase vouchers are created like any other product. In addition, they need the product field `InstantVoucherProduct`, which consists of four values. All four are placed one after another in one field and enclosed by ``. ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} <1>Gutscheinprodukt y/n<2>ChargenID<3>Vorlagenwert überschreiben y/n<4>Nummer neu generieren y/n ``` | Position | Meaning | Values | | - | - | - | | `<1>` | whether this product is a voucher product | `y` active. Any other value means inactive, and the remaining three values are not evaluated | | `<2>` | the batch ID to which the vouchers belong | the name of the batch | | `<3>` | where the voucher value comes from | `y` the product price is the voucher value and overrides the value from the template or pool. Any other value keeps the value from the template or pool | | `<4>` | where the number comes from | `y` the shop generates a new number. Any other value takes it from the pool | ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} <1>y<2>Kaufgutscheine<3>y<4>y ``` > [!WARNING] > > The values are checked for `y`, not for `n`. A typo or an empty field at position 1 turns the product into an ordinary item that is sold without a voucher. The shop does not report this. > [!NOTE] > > Variants are generally used for the value levels. A "voucher value" variant with the levels 10, 20, 50, 100, 200, and 500 euros is the usual setup. In combination with `<3>` set to `y`, the voucher value then results directly from the selected variant. ### Step 4: Providing voucher numbers The numbers come from one of two sources. Position 4 in the product field decides which one. | Position 4 | Source | What you prepare | | - | - | - | | `y` | The shop generates a new number | a voucher template in the voucher generator of the online service area | | anything else | The shop takes it from a pool | import of a voucher number pool from your merchandise management or ERP system | > [!NOTE] > > In both cases, each voucher must be assigned a batch ID, because this exact ID is what you enter at position 2 of the product field. Without a matching batch, the shop finds no numbers. If you have specified at position 3 that the product price determines the voucher value, the shop overrides two values, regardless of the source: * The stored currency is replaced by the currency of the subshop. * The voucher value from the template or pool is replaced by the product price. > [!WARNING] > > With a pool, your upstream system must ensure that enough numbers are always available. If none are left, the voucher product cannot be purchased. As a rule, the check only takes place when the order is placed and not when the product is added to the basket. The customer therefore goes through the entire ordering process before seeing the error message. Therefore, actively monitor the fill level of the pool instead of relying on the message. > [!NOTE] > > The format of the import file is described in separate documentation, which you can request from WEBSALE AG. Guide: Create or import vouchers ### Step 5: Defining payment methods Because the buyer sees the voucher number immediately after payment and can redeem it right away, you should only sell purchase vouchers for online payment methods such as credit card, PayPal, or Sofortüberweisung. With invoice or cash on delivery, the customer would already have the equivalent value in hand before the money reaches you. You define the approval individually for each payment method, in the respective `` section of the `shop.config`. ```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} InstantVoucherProducts-Allow = yes ``` > [!NOTE] > > `XXX` stands for the respective payment method, so the section is called ``, for example. If at least one purchase voucher is in the basket, the shop only offers the payment methods for which this entry is set to `yes`. Reference: PaymentXXX-Txt ### Step 6: Marking purchase vouchers in the templates (optional) Purchase vouchers can be enclosed separately to display them differently from ordinary products, for example with a notice about the immediate download. | Template | Section | | - | - | | Product overview page `ws_category.htm` and product detail view `ws_product.htm` | `PR-InstantVoucherProduct` | | Basket page `ws_basket.htm` | `BASKET-PR-InstantVoucherProduct` | ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {PR-InstantVoucherProduct} Diesen Gutschein erhalten Sie sofort nach der Bezahlung zum Ausdrucken. {/PR-InstantVoucherProduct} ``` Reference: PR-InstantVoucherProduct · BASKET-PR-InstantVoucherProduct ### Step 7: Displaying the voucher number and download link The generated number and the link to the PDF file can be output in three places: on the order confirmation page `ws_confirm.htm`, in the order confirmation email, and in the order history. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {@BASKET-PR-Data} {BASKET-PR-InstantVoucherProduct} {BASKET-PR-InstantVoucherProductData} {@BASKET-PR-InstantVoucherProductData} Gutscheinnummer: ~BASKET-PR-InstantVoucherProductData_VoucherNumber~ Gutschein herunterladen {/@BASKET-PR-InstantVoucherProductData} {/BASKET-PR-InstantVoucherProductData} {/BASKET-PR-InstantVoucherProduct} {/@BASKET-PR-Data} ``` > [!NOTE] > > The inner loop is necessary because a basket item can contain multiple vouchers. If someone buys five vouchers of the same kind, five numbers and five PDF files are created in a single item. > [!NOTE] > > `BASKET-PR-InstantVoucherProductData_PDFLinkPart` only provides the latter part of the address. `WS-Start` must precede it, which is why the two tags appear directly one after the other in the example. The parameter is encrypted, provided with a checksum, and contains the shop ID, so other people's vouchers cannot be retrieved through it. Reference: BASKET-PR-Data · BASKET-PR-InstantVoucherProduct · BASKET-PR-InstantVoucherProductData · BASKET-PR-InstantVoucherProductData\_VoucherNumber · BASKET-PR-InstantVoucherProductData\_PDFLinkPart · WS-Start ### Step 8: Creating the template for the PDF download The voucher for printing is generated from a dedicated template. Three settings are required for this. #### 8.1 Assigning the template in the configuration ```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} InstantVoucherPDF = ws_instant_voucher.htm # Template für den PDF-Download des Gutscheins ``` #### 8.2 Creating the template Create the template under the name you just assigned in your template directory, for example under `benutzer/templates`, or in a multilingual shop in the directory of the respective subshop. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} Gutschein Betrag: ~INSTANTVOUCHER-Amount~ ~INSTANTVOUCHER-CurrencyCode~ ~INSTANTVOUCHER-CurrencySymbol~ Nummer: ~INSTANTVOUCHER-VoucherNumber~ Gültig bis: ~INSTANTVOUCHER-ValidUntil_day~.~INSTANTVOUCHER-ValidUntil_month~.~INSTANTVOUCHER-ValidUntil_year~ ``` The `INSTANTVOUCHER-` family comprises exactly these seven tags. | Tag | Content | | - | - | | `INSTANTVOUCHER-Amount` | the voucher amount, already in the shop's price format | | `INSTANTVOUCHER-CurrencyCode` | the currency code, for example `EUR` | | `INSTANTVOUCHER-CurrencySymbol` | the currency symbol | | `INSTANTVOUCHER-VoucherNumber` | the voucher number | | `INSTANTVOUCHER-ValidUntil_day` | the day of validity | | `INSTANTVOUCHER-ValidUntil_month` | the month of validity | | `INSTANTVOUCHER-ValidUntil_year` | the year of validity | > [!WARNING] > > The three date tags remain empty if no expiry date is stored for the voucher. The line "Valid until: `..`" then appears with two bare dots on the printed voucher. Therefore, enclose the line, for example with `{INSTANTVOUCHER-ValidUntil_year}`, so that it only appears when a date is present. > [!NOTE] > > For a physical store, you can additionally print the voucher number as a barcode on the template and have it scanned at the checkout. The tag `WS-BarcodeURL` generates the barcode as an image. Reference: Templates section · INSTANTVOUCHER- · WS-BarcodeURL #### 8.3 Defining the file name of the PDF file ```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} InstantVoucherPDFFilename = gutschein.pdf ``` > [!NOTE] > > This name appears in the customer's download dialog. A descriptive name like `gutschein.pdf` is worth more here than a technical designation, because the file should remain easy to find in the buyer's download folder. Reference: PDFGenerator section ### Step 9: Providing the error message If something goes wrong when drawing or generating a voucher number, the customer needs a text. Store it in the `` section of the `shop.config`. ```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} InstantVoucherError = Es ist ein Fehler aufgetreten. Bitte versuchen Sie es erneut oder wenden Sie sich an den Shopbetreiber. ``` > [!WARNING] > > This message is the only notice the customer receives in the event of an error, and it typically only appears when the order is placed. Without a stored text, the ordering process aborts without explanation. Reference: NotifyMessages-Txt ### Step 10: Offering the download in the order history If the customer deletes the confirmation email, without this step they have no way of getting to their voucher. Therefore, add the download to the order history `ws_order_history.htm`. ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} {@OH-S-Item} {@OH-S-InstantVoucherProduct} Gutschein ausdrucken Gutscheinnummer: ~OH-P-Number~ {/@OH-S-InstantVoucherProduct} {/@OH-S-Item} ``` Reference: OH-S- · OH-P- · WS-Start ## What you should keep in mind > [!WARNING] > > The purchase voucher can **not** be attached as a PDF to the order confirmation email. The customer can only access it via a download link, either in the order confirmation from step 7 or in the order history from step 10. Therefore, set up both options if possible. > [!NOTE] > > If you have questions about the setup, contact the WEBSALE support team. ## Related topics * Guide: Offering vouchers: Overview * Guide: Create or import vouchers * Guide: Provide voucher entry * Use case: Offer purchase vouchers for printing with multiple designs ## Related topics - [Vouchers in the basket](https://dokumentation.websale.de/en/v8s/referenz/tags/basket/gutscheine-im-warenkorb.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) - [INSTANTVOUCHER- (Printable purchase vouchers)](https://dokumentation.websale.de/en/v8s/referenz/tags/instantvoucher-kaufgutscheine.md) - [VOUCHER- (Voucher)](https://dokumentation.websale.de/en/v8s/referenz/tags/voucher-gutschein.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.