Troubleshooting Gift Certificates
Below you will find a list of common errors that may occur while using the Gift Certificates feature, and information on how to troubleshoot them.
Gift Certificates not generating
If your gift certificates won’t generate or are remaining in “Pending” status, please check the following:
- Ensure the order is in a paid status: For additional information you can read the FAQ about gift certificates generation and order statuses on WooCommerce.
- Background processing: Your site must support background processing for gift certificates to generate. To check this, go to WooCommerce > Status > Tools and run the Background Processing Test. If your site fails, please contact your host to enable background processing/loopback connections.
- Security plugins: Gift Certificates must access the HTML generated for each gift certificate to convert it to a PDF. Some security plugins, such as 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 Gift Certificates and many other WooCommerce plugins. Gift Certificates 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 gift certificates 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 gift certificates.
- cURL timeout error: If you’re receiving this error (Could not generate gift certificate PDF: Cannot load gift certificate HTML: cURL error 28: Connection timed out after 5001 milliseconds.), you may want to increase your timeout using this code. If you are unsure where to input this code, you can contact your hosting provider for more information.
Blank gift certificates
If gift certificates are generating but are blank, please check the following:
- Maintenance mode plugins: Is your site publicly available? This is required for gift certificate generation to work. Be sure to disable any maintenance mode plugins. Gift certificates are generated from an HTML file on your site, so Gift Certificates must be allowed to request and read this HTML file to generate the gift certificate, which may be prevented by these types of plugins.
- Background processing: Your site must support background processing for gift certificates to generate. To check this, go to WooCommerce > Status > Tools and run the Background Processing Test. If your site fails, please contact your host to enable background processing/loopback connections.
Slow gift certificate generation
While using PHP 7.0+ will improve gift certificate generation speed, generation times are largely influenced by the gift certificate 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 gift certificates, we recommend keeping these images less than 2000px (i.e. smaller than a printed page) to allow the gift certificate to generate in a reasonable time.
Blurry gift certificates
If your gift certificates look blurry on your device, 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 correctly. 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 gift certificate looks blurry when printed, that can be due to a number of factors:
- If your gift certificate PDF is smaller than the page size being printing on, it may be scaled by your print manager past 100%, resulting into 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 gift certificate image, which may look large as an on-screen PDF but should scale down and look sharp when printed. Please ensure your gift certificate template background image is high-resolution / 300 DPI and that you’ve set this as the image DPI for your gift certificate.
Be sure to test your gift certificate image when initially configuring the gift certificate template by manually adding and downloading a gift certificate 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
Gift Certificates supports using non-ASCII characters, such as Cyrillic or Mandarin, on a generated gift certificate. 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.
If the included fonts don’t work well for your language, you can use a small code snippet 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.
Scanning barcodes
If you’re having issues when scanning barcodes, please check the following:
- Ensure the gift certificate template is using the QR code barcode type: While other barcodes may be used for external scanners, Gift Certifcates only support 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 gift certificates codes.
Other Issues
- Check the FAQ.
- Is the gift certificate's 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 gift certificates, as they’ll lose this resolution when compressed. Ensure resolution is at 300 DPI and that your gift certificate template background image is configured at this setting as well.
