WooCommerce PDF Product Vouchers

Overview

↑ Back to top

WooCommerce PDF Product Vouchers lets you create and sell customizable vouchers for products such as tours, events, classes, or any goods/services that are purchased in your WooCommerce store or physical location. Your customers can purchase vouchers for themselves or others and choose voucher images from your preset options. After purchasing, the customer can access the PDF voucher which can be redeemed online or in person. You can even couple PDF Product Vouchers with the Name Your Price plugin to let your customers determine the value of their vouchers!

Requirements

↑ Back to top

• WooCommerce 3.5+
• PHP 7.1+
• The mbstring PHP extension.
• Loopback connects – required to generate voucher PDFs, as the plugin must retrieve the HTML for each voucher.
• SSL certificate – required to support barcode scanning, as browsers often prohibit scanning for non-HTTPS sites.

Installation

↑ Back to top

1. Ensure your store meets the plugin requirements.
2. Download the extension from your WooCommerce dashboard.
3. Go to Plugins > Add New > Upload and select the ZIP file you just downloaded.
4. Click Install Now and then Activate.
5. Click Configure and read the next section to learn how to setup the plugin.

Getting started

↑ Back to top

There aren’t any special settings to configure, so you can jump right in and start setting up your voucher templates!

Creating a voucher template

↑ Back to top

Follow the steps below to create a voucher template:

1. Go to WooCommerce > Vouchers > Voucher Templates.
2. Click Add Voucher Template.
3. On the General tab, determine the template name, voucher type, whether the voucher can be redeemed online, and various formatting settings.
4. On the Images tab, set the background image by choosing one of the default options or by uploading your own image. You can add more images to let customers choose their desired background, but they must have the same dimensions as the primary image. Field placements must match between various images, since swapping backgrounds does not reposition the voucher fields. When you create your background images, we recommend using high resolution / 300 DPI (instead of the default 72 DPI), and setting the voucher to a corresponding level.
5. Work through the other voucher template settings to add fields to your template and determine their positioning:
   • Logo
   • Product Name
   • Product SKU
   • Product Price
   • Product Quantity
   • Voucher Number (required if online redemptions are enabled)
   • Expiration Date
   • Purchaser Name
   • Recipient Name
   • Recipient Email
   • Message
   • Barcode
6. Click Publish to save your template.

Here’s a video example of creating a new voucher template:

Creating a voucher product

↑ Back to top

After creating a voucher template, you can attach it to a product. When customers buy this voucher product, they will generate a voucher to use on any redemption product(s). Follow the steps below to create a voucher product:

1. Go to Products and select the product in question.
2. Check the Has Voucher box.
3. Select your template from the Voucher Template field.
4. Update the Tax status field based on the voucher type.
5. Click Update.

Variable products

If you’re working with a variable product, you can configure the Has Voucher and Voucher Template settings for each variation. The variation name will be included in the voucher’s Product Name section. If your template doesn’t include Product Name, we recommend adding Product SKU to the template and setting unique SKUs for each variation.

Name Your Price products

By default, vouchers use the price you’ve set for the product or its variations as the voucher’s value. To let customers enter their own voucher values instead, you can use PDF Product Vouchers with Name Your Price by checking the Has Voucher and Name Your Price boxes. The voucher will now use whatever the customer enters for the product price instead of the preset price. We recommend using multi-purpose voucher templates for Name Your Price products. Be sure to enable the Product Price field in the voucher template so the voucher’s value is clear!

Configuring redemption products

↑ Back to top

You can configure products to use designated single-purpose vouchers to offset 100% of the product’s price. Follow the steps below to setup a product to be purchasable by voucher:

1. Go to Products and select the product in question.
2. In the Redemption Vouchers field, list the voucher template(s) that customers can use to buy this product.
3. Click Update.

Understanding voucher types and taxes

↑ Back to top

There are two types of vouchers – single-purpose vouchers and multi-purpose vouchers:

• A single-purpose voucher is used for a particular product.
• A multi-purpose voucher can be used for different products.

The voucher type influences how the voucher is taxed (at purchase or at redemption), and therefore the voucher’s value and how it is redeemed. While PDF Product Vouchers will make suggestions for how to tax a voucher based on its type, you are responsible for understanding the tax regulations that impact your store. If you’re not sure whether a voucher should be taxed at purchase or not, please consult your tax attorney or accountant. Our documentation can help guide your decisions around voucher taxation, but tax compliance is your responsibility as a merchant, so please be careful to choose the right options for your store. If your store is based in the EU, you may find this reference on EU VAT rules for vouchers helpful; US laws are similar in scope.

Single-purpose vouchers

↑ Back to top

Single-purpose vouchers can be redeemed for a single, specific purpose, such as a particular good or service. This is a true voucher that’s traded in for the desired product or service.

Taxability

Since a single-purpose voucher is associated with a specific product, you know the tax class that will be associated with the voucher’s redemption ahead of time. As such, single-purpose vouchers are typically taxed at purchase, so no taxes are assessed when redeeming the voucher. When you attach a single-purpose voucher template to a voucher product, we generally recommend updating the Tax status field to match the tax class of the redemption product.

Voucher value

The apparent value of a single-purpose voucher will vary based on your store’s tax display settings (WooCommerce > Settings > Tax):

• If your product prices exclude taxes, the voucher value will reflect the product price only:

• If your product prices include taxes, the voucher value will include the product’s taxes.

Redemptions

Since single-purpose vouchers are taxed at purchase, they can only be redeemed in multiples of the product price. This is because single-purpose vouchers offset the entire price of a particular product. For example, if you’re using a voucher on a product that is $50, the redemption amount must be $50. If you’re buying multiple quantities of this product, the redemption amount must be a multiple of 50 (e.g. $100, $150, $200, etc.). If you use tax-inclusive product pricing, the redemption amount should include taxes, too (e.g. $50 + taxes, $100 + taxes, etc.). In either case, taxes are calculated automatically for the voucher redemption.

Multi-purpose vouchers

↑ Back to top

Multi-purpose vouchers can be redeemed for any product or service. This is more like a gift certificate that can be used to offset the cart total, not just a particular product.

Taxability

Since multi-purpose vouchers can be redeemed on any product, you can’t know the tax class that will be associated with the voucher’s redemption ahead of time. As such, multi-purpose vouchers are typically not taxed at purchase. Instead, tax is assessed on the items purchased when the voucher is redeemed. When you attach a multi-purpose voucher template to a voucher product, we generally recommend updating the Tax status field to “None”.

Voucher value

As multi-purpose vouchers are generally untaxed, the apparent value of the voucher won’t change based on your tax settings.

Redemptions

Since multi-purpose vouchers aren’t restricted to particular products, the redemption amount can be any value. As multi-purpose vouchers are generally not taxed, the redemption will apply to the order total.

Purchasing and redeeming vouchers

↑ Back to top

Purchasing vouchers

↑ Back to top

When purchasing a voucher, the product options will vary based on how you’ve setup the voucher template, including:

• Which voucher fields are available and require customer input
• If voucher fields are required or optional
• If alternative images are available

The quantity field for the voucher product will behave differently based on whether you added the Product Quantity field to the voucher template:

• If Product Quantity is included in the template, changing the product quantity will create one voucher with multiple uses attached.
• If Product Quantity isn’t included in the template, changing the product quantity will create separate vouchers for each quantity ordered.

If you sell items like tickets, where quantity increases are expected but the voucher details shouldn’t vary, you should ensure that Product Quantity is added to the voucher template.

Receiving vouchers

↑ Back to top

Once the voucher product is ordered, a pending voucher is created. The voucher will generate when the order is marked as paid (typically Processing or Completed status, depending on your Grant Access to Downloadable Products After Payment setting, found under WooCommerce > Settings > Products > Downloadable Products). Once generated, the voucher will move to active status. At this point, the voucher purchaser will receive the voucher PDFs as attachments in the Processing Order and Completed Order emails (WooCommerce > Settings > Emails) and can find the voucher in their My Account > Vouchers area. If the Recipient Email field is included on the voucher template, a separate email will be sent to that email address with the voucher PDF attached. This is perfect for vouchers that will be used as gifts! You can customize the Recipient Email from the WooCommerce > Settings > Emails page.

Redeeming vouchers online

↑ Back to top

Customers can redeem vouchers online during checkout by entering the voucher code in the Coupon Code field and click Apply Coupon. For single-purpose vouchers:

• The products will be checked to see if they’re redeemable for that voucher. If the cart includes at least one redeemable product, then the voucher is applied to the highest-priced item eligible for redemption. This discounts 100% of the item’s price, regardless of the voucher value.
• The voucher value is applied before taxes are calculated, so taxes are assessed on the subtotal after the voucher is deducted.

For multi-purpose vouchers:

• The cart total will be offset by the voucher value. If only part of the voucher’s value is used, it is considered partially redeemed and can be used again at a later date.
• The voucher value is applied after taxes are calculated, so taxes are assessed on the subtotal before the voucher is deducted.

Click here to learn how to redeem vouchers manually or via barcode scanning.

Managing vouchers

↑ Back to top

You can manage your site’s vouchers from the WooCommerce > Vouchers page.

Adding vouchers

↑ Back to top

You can manually add a voucher for a customer, which will appear in their My Account > Vouchers area. Follow the steps below to manually add a voucher:

1. Go to WooCommerce > Vouchers and click Add New Voucher.
2. Select the voucher product and click Add Voucher.

3. Update the voucher details as needed.
4. Set the Voucher Status to “Active” so the customer can use the voucher.
5. Click Save Voucher.

Editing vouchers

↑ Back to top

To view or edit a voucher, go to WooCommerce > Vouchers and select the voucher from the list. You can edit most voucher details from the Edit Voucher page, which is similar to the Edit Order interface. If you make any changes to the voucher, be sure to regenerate the voucher PDF by selecting “Generate PDF” from the Voucher Actions menu. If you would like to generate the voucher PDF files in bulk, go to WooCommerce > Vouchers and select the checkbox next to all the vouchers you wish to generate. Once the vouchers are selected, choose Generate PDF from the Bulk Actions dropdown and click Apply.

Downloading vouchers

↑ Back to top

To download the voucher PDF, go to WooCommerce > Vouchers, select the voucher in question, and click View Voucher PDF.

Redeeming vouchers

↑ Back to top

Manually redeeming vouchers

You can redeem vouchers for either their full or partial value, and can redeem vouchers multiple times until their entire value is used up. Both Adminstrators and Shop Managers have access by default to manually redeem vouchers. To manually redeem a voucher:

1. Go to WooCommerce > Vouchers and either:
   • Select the check icon in the Actions column, or
   • Select the voucher in question and click Redeem.
2. Enter the amount you want to redeem.
3. Optionally enter a note/reason for the redemption.
4. Click Redeem.

Once a voucher has been fully redeemed (i.e. there’s no remaining value), the status will change from “Active” to “Redeemed”.

Scanning voucher barcodes

If your voucher template includes a QR code, you can scan this code to redeem the voucher. While using a device capable of reading QR codes, follow the steps below to scan a voucher’s QR code:

1. Go to WooCommerce > Vouchers.
2. Select Redeem Voucher.
3. Click Scan QR Code.

Single-purpose vouchers are redeemed based on quantity, so one scan is equal to one quantity redeemed. If a voucher has more than one quantity available, you can scan it multiple times to redeem the desired quantity. Watch the recording below of redeeming a single-purpose voucher: Multi-purpose vouchers are redeemed based on amount, so after scanning you’ll need to enter the amount to redeem. Watch the recording below of redeeming a multi-purpose voucher:

Voiding vouchers

↑ Back to top

You can void vouchers to revoke the remaining value from customer use. This is particularly useful if you’ve refunded the order where the voucher was purchased, since refunding an order doesn’t automatically update purchased vouchers. A void will always nullify the entire remaining amount and will change the status from “Active” to “Voided”. Follow the steps below to void a voucher:

1. Go to WooCommerce > Vouchers and either:
   • Select the X icon in the Actions column, or
   • Select the voucher in question and click Void.
2. Optionally enter a note/reason for the void.
3. Click Void.

Frequently asked questions

↑ Back to top

Q: Are voucher numbers secure? A: Every voucher uses a unique, random 8-character alphanumeric string as the voucher number. For vouchers ordered from your store, the voucher number also includes the order number as a suffix to provide an additional check on your voucher numbers.

---

Q: Why are my vouchers only generated when the order is marked Completed? They should be generated when the order is in Processing status. A: Voucher generation timing is dictated by your WooCommerce download settings. If you go to WooCommerce > Settings > Products > Downloadable Products, you can check the Grant access to downloadable products after payment setting to trigger voucher generation in Processing status.

---

Q: Does PDF Product Vouchers work with WooCommerce Coupons? A: If your voucher template allows online redemptions, vouchers can be redeemed online via the Coupon input in the cart/checkout process. However, vouchers are managed separately from coupons (i.e. in the WooCommerce > Vouchers page instead of the WooCommerce > Coupons page). Redeeming vouchers online requires WooCommerce 3.2 or newer.

---

Q: How can I prevent the same voucher from being used twice? A: To prevent vouchers from being reused, ensure that your voucher template includes the Voucher Number field. This number is unique and random, so it can’t be forged or reproduced. This field is required if your template allows online redemptions.

---

Q: My customer ordered more than one quantity of a voucher product, so why can they only download one voucher? How do I generated one voucher for each quantity purchased? A: The voucher template’s Product Quantity field determines how the voucher will behave when more than one quantity of the voucher product are purchased. To generate separate vouchers for each quantity, remove the Product Quantity field from the voucher. This will create separate vouchers, but all voucher details (e.g. Recipient Name) will be identical. Increasing product quantity does not add additional fields (e.g. Recipient Name 1, Recipient Name 2, etc.) The voucher number, however, will be unique. To let customers enter unique values for each voucher product purchased, you must force customers to purchase voucher products one at a time. You can do this by going to the product’s Inventory tab and enabling the Sold Individually setting. This won’t prevent the customer from purchasing more than one voucher, but will require them to be added to their cart separately. This lets the customer add multiple voucher products with different voucher field inputs. Each voucher will show as a separate line item, even if the field inputs are identical. If you want to only let customers purchase one voucher per order, this would require some custom code since WooCommerce core doesn’t behave this way (product meta, such as voucher details, make each product unique). Click here to view a sample snippet to disable adding more than one of a particular product voucher to the cart, which you can modify if needed.

---

Q: Can I import voucher products? A: Sure! You can use the following meta keys to add voucher products:

• _has_voucher: Enter “yes” to check the Has Voucher box for this product.
• _voucher_template_ID: Enter the template ID for the voucher template associated with this product. You can find the template ID by going to WooCommerce > Vouchers > Voucher Templates and hovering over the template name.

---

Q: Can customers enter their own voucher values to use the voucher like a gift certificate? A: You can use the Name Your Price extension to let customers enter their own voucher values. Be sure to enable the Product Price field in the voucher template so the voucher’s value is clear!

---

Q: Is PDF Product Vouchers compatible with WooCommerce Bookings? A: Bookings fields aren’t supported on vouchers, but this is on our roadmap! If this feature is important to you, please click here to add your vote! Please note that vouchers can still be redeemed toward bookable products.

---

Q: What does this error mean – “PDF error: Image file has no extension and no type was specified”? A: You must upload an actual image file (e.g. JPG or PNG) to your voucher template. PDF Product Vouchers will convert this image into a PDF when it generates the voucher.

---

Q: Does PDF Product Vouchers support PHP 8? A: Yes, it does! PHP 8 compatibility has been implemented in version 3.9.0. Make sure to update this plugin to start utilizing it right away. Q: Can vouchers be automatically applied to recurring subscriptions? A: Vouchers can not be automatically applied to recurring subscriptions. If a customer has subscriptions that are automatically renewed, they will need to renew early before the next payment date to use the voucher on the renewal. To do that, go to My Account > Subscriptions > Renew now, then enter the voucher code at checkout.

---

Q: Is there a way for me to export my vouchers? A: To export any custom post type to your site, including but not limited to all of the hidden post metadata, we recommend using the WP All Export plugin. Just a note that when installing the plugin, you should perform an export with all fields by clicking the “Add All” button when preparing columns. This will allow you to see all of the data types that can be utilized with this export plugin.

---

Troubleshooting

↑ Back to top

Vouchers not generating

↑ Back to top

If your vouchers won’t generate or are remaining in “Pending” status, please check the following:

• Ensure the order is in a paid status: Click here to read our FAQ about voucher generation and order statuses.
• Background processing: Your site must support background processing for vouchers to generate. To check this, go to WooCommerce > Status > Tools and run the Background Processing Test. PDF Product Vouchers and many other WooCommerce features/plugins require background processing. If your site fails, please contact your host to enable background processing/loopback connections. While some hosts may identify this as a security issue, there’s no security threat to using a loopback connection and, if done correctly, it won’t increase server usage. Quality hosts will mitigate increased server usage with rate limiting.
• Security plugins: PDF Product Vouchers must access the HTML generated for each voucher to convert it to a PDF. Some security plugins, like WordFence or iThemes Security, can block this and should be disabled or reconfigured to permit this access.
• Host files: For developers – hosts files to resolve a site to a different domain can’t be used with PDF Product Vouchers and many other WooCommerce plugins. PDF Product Vouchers uses wp_safe_remote_* requests to get data from itself, and these requests require a domain name. If your site is pointing to a domain from a hosts file, rather than a public site, these requests will fail.
• BasicAuth: If your site is behind BasicAuth, background requests to generate vouchers will fail to complete. For example, WP Engine staging sites often use basic authentication to block site access (you’ll see a popup for credentials when trying to access the site). Please disable basic authentication to generate vouchers.
• cURL timeout error: If you’re receiving this error (Could not generate voucher PDF: Cannot load voucher HTML: cURL error 28: Connection timed out after 5001 milliseconds.), click here for a code snippet to increase the timeout.

Blank vouchers

↑ Back to top

If vouchers are generating but are blank, please check the following:

• Maintenance mode plugins: Is your site publicly available? This is required for voucher generation to work, so please disable any maintenance mode plugins. Vouchers are generated from an HTML file on your site, so PDF Product Vouchers must be allowed to request and read this HTML file to generate the voucher, which may be prevented by these types of plugins.
• Background processing: Your site must support background processing for vouchers to generate. To check this, go to WooCommerce > Status > Tools and run the Background Processing Test. PDF Product Vouchers and many other WooCommerce features/plugins require background processing. If your site fails, please contact your host to enable background processing/loopback connections. While some hosts may identify this as a security issue, there’s no security threat to using a loopback connection and, if done correctly, it won’t increase server usage. Quality hosts will mitigate increased server usage with rate limiting.

Slow voucher generation

↑ Back to top

While using PHP 7.0+ will improve voucher generation speed, generation times are largely influenced by the voucher template background image. As the background image increases, so does the time to generate the PDF. At checkout, this means that an order that’s immediately paid can take longer to generate and display on the Order Received page. If you use high-resolution vouchers, we recommend keeping these images less than 2000px (i.e. smaller than a printed page) to allow the voucher to generate in a reasonable time.

Blurry vouchers

↑ Back to top

If your PDF vouchers look blurry on screen, this is most likely due to a setting with your PDF viewer (e.g. Acrobat, Preview, etc.). By default, most PDF viewers will try to display an image the way they think it will appear when printed, but this doesn’t always work right. You can change this setting in your PDF viewing application. For example, in Preview, you can go to Preferences > PDF and change the Define 100% scale as setting to “1 point equals 1 screen pixel”. If your PDF voucher looks blurry when printed, that can be due to a number of factors:

• If your voucher PDF is smaller than the page size you’re printing on, it may be scaled by your print manager past 100%, resulting in a blurry, unfocused image. Try changing your print settings to scale no higher than 100%.
• Sometimes images on screen simply look better than printed versions, due to the physical differences between a pixel on a monitor and a pixel printed to a piece of paper. In general, images look better on screen and require a higher resolution when printed to match the on-screen version. To solve this, you can start with a higher resolution voucher image, which may look large as an on-screen PDF but should scale down and look sharp when printed. Please ensure your voucher template background image is high-resolution / 300 DPI and that you’ve set this as the image DPI for your voucher.

Be sure to test your voucher image when initially configuring the voucher template by manually adding and downloading a voucher for yourself to get a sense of how the chosen image will look in PDF form, how the text fields are arranged, and how it will look when printed by your customers.

Special character support

↑ Back to top

PDF Product Vouchers supports using non-ASCII characters, such as Cyrillic or Mandarin, on a generated voucher. As system fonts are used, your server / hosting environment should support this. However, if you find that special characters aren’t recognized properly (or are replaced with ? symbols), you can use an external font instead with broader character support. Starting with version 3.9 of PDF Product Vouchers, Google Fonts have been integrated to add additional fonts to your vouchers. This includes a number of popular fonts, including Noto Sans which has pretty wide character support and works well for most special characters. If the included fonts don’t work well for your language, you can use the small code snippet below to register more fonts. We recommend taking a look at Google Fonts previews to find a font which works best for your brand and language.

add_filter( 'wc_pdf_vouchers_google_fonts_available', function( $fonts ) {
    return array_merge( $fonts, [ 'Oxygen', 'Muli', 'Robot Condensed' ] );
} );

Scanning barcodes

↑ Back to top

If you’re having issues when scanning barcodes, please check the following:

• Ensure voucher template is using the QR code barcode type. While other barcodes may be used for external scanners, PDF Product Vouchers only supports reading QR codes for scanning redemption.
• Set the barcode foreground color to black. This should make it easier for your scanner to detect and properly scan the barcode.
• Seeing the “Only secure origins allowed” error? This is likely because your browser doesn’t allow camera access without an SSL certificate. Your site must include an SSL certificate to scan voucher codes.

Other Issues

↑ Back to top

Having difficulty with the plugin?

• Please ensure your site meets the plugin requirements.
• Check the FAQs to see if they address your question.
• Is the voucher text blown up or generally not looking right? Please note that you cannot use image-compression plugins like WP SmushIT when trying to add retina-dpi or high-resolution vouchers, as they’ll lose this resolution when compressed. Ensure resolution is at 300 DPI and that your voucher template background image is configured at this setting as well.
• If you’re experiencing a different issue, please contact the support team for assistance.

Questions & support

↑ Back to top

Have a question before you buy? Please fill out this pre-sales form. Already purchased and need some assistance? Please check out our troubleshooting tips and frequently asked questions for common issues or contact support via the help desk if you need more help.