WooCommerce PDF Product Vouchers Developer Documentation

Version 3.0 of this extension was a complete refactor in order to make the plugin as flexible for merchants and developers alike. To that end, hooks — actions and filters — are used to allow you to customize the generated vouchers, voucher templates, or workflows while using vouchers. Our goal is to ensure this plugin is easy to work with for customizations. If a hook doesn’t exist where you think it should, please submit a ticket so we can consider its addition. This reference lists helpful filters, actions, and methods and is meant to be a directory. Please see the plugin’s inline documentation for additional details on parameters, returned values, and usage, or example usage.

Please be aware that this document is meant for developers to use as a reference, and some of these code samples are structural samples rather than working snippets. We do not support or do plugin customizations as per our support policy. You can get in touch with an expert for help with customizations.
If you need help changing this code or extending it, we recommend getting in touch with a WooExpert or a developer at Codeable.

Data Structure

↑ Back to top
WooCommerce PDF Product Vouchers leverages 2 main data structures: voucher templates and generated vouchers. Both of these are custom post types, and store either template data for generating vouchers, or the data for a generated, redeemable voucher record.

Voucher Templates

↑ Back to top
Post type: wc_voucher_template The voucher template post serves as a guide for a generated voucher. The post contains several pieces of postmeta to create the template, such as field positions. However, here’s a selection of pertinent postmeta for a voucher template:

meta key data type stored value
_thumbnail_id int media attachment ID for the voucher background image
_image_ids serialized array any alternative background images’ attachment IDs
_voucher_image_dpi int The resolution / DPI of the background image
_expiration_date_days_to_expiry int the days until a voucher expires after purchase (can be blank / unset for “never”)

Generated Vouchers

↑ Back to top
Post type: wc_voucher Each generated voucher for a purchase, or a manually created voucher, will have a new voucher post, which stores data about voucher fields, redemption(s), and any voided value. The post object itself has a couple of important pieces of data:
  • The post name is the voucher number, e.g., V01KERN4-166 — this represents a psuedo-random, unique, 8-character number, and if purchased, the associated order number (respects filtered order numbers, such as with Sequential Order Numbers Pro).
  • The post status indicates the voucher status, such as “Active”, and is prefixed in the database: wcpdf-active. When using helper methods, the prefix typically is not needed.
The voucher record also contains voucher details and transactional history as post meta.
meta key data type stored value
_order_id int if purchased, the associated order ID for the voucher purchase
_product_id int The product / variation ID that was purchased to generate the voucher
_order_item_id int The order item ID for a voucher purchase (if purchased)
_thumbnail_id int the selected voucher background image’s attachment ID
_voucher_currency string the currency in which the voucher value is denominated
_product_price int the price of the product at purchase, and therefore the voucher value
_product_quantity int quantity purchased, which is multiplied by price to get voucher value
_remaining_value int the remaining value of the voucher
_product_quantity int quantity purchased, which is multiplied by price to get voucher value
_download_count int the number of times the voucher has been downloaded
_redemptions serialized array If there are redemptions, an array of redemption dates, values, and / or unused quantities
Other voucher fields are included if set on the template, such as purchaser name, expiration date (unix timestamp), message, and others. If the voucher has been voided, the void date, value, and reasons are available.

Product Data

↑ Back to top
To associate a voucher with a product or variation, the product post will store two pieces of data:
meta key data type stored value
_has_voucher string yes or no
_voucher_template_id int the voucher template’s post ID

Customizing Generated Vouchers

↑ Back to top

Filtering Voucher Data

↑ Back to top

wc_pdf_product_vouchers_voucher_filename

Filters the voucher filename.
@since
1.2.0
@param
string $filename voucher filename
@param
\WC_Voucher $voucher the voucher object
Allows for adjustments of the default voucher filename.

wc_pdf_product_vouchers_new_voucher_data

Filters new voucher data.
@since
3.0.0
@param
array $data voucher data
@param
array $args {
  • @type int $voucher_template_id the voucher template to be used for generating the PDF
  • @type int $order_id (optional) the order id that this voucher was generated from
  • @type int $user_id (optional) the user id the voucher is assigned to
    • }
This lets you adjust the voucher post object’s data while it’s created.

wc_pdf_product_vouchers_get_voucher_currency

Filters the voucher currency.
@since
3.0.0
@param
string $currency voucher currency
@param
\WC_Voucher $voucher the voucher object
Helpful if voucher currency should differ from order currency, or be changed from the historical value.

wc_pdf_product_vouchers_voucher_field_settings

Filters settings for a voucher field.
@since
3.0.0
@param
array $settings default field settings
@param
string $field_id field identifier
@param
string $data_type field data type

Filtering Voucher Fields

↑ Back to top

wc_pdf_product_vouchers_generated_voucher_number

Filters the generated voucher number.
@since
3.0.0
@param
string $number generated voucher number
@param
string $prefix voucher number prefix, if available
@param
string $random random part of the voucher number
@param
int $order_id order ID associated with the voucher, if available
This filters the generated voucher number, allowing for the addition of a prefix, removing the associated order ID, or other voucher number adjustments. If you change the voucher’s random portion (the 8 char letters + numbers), note that you should ensure uniqueness of the voucher number yourself within your customization! 
// Example: remove order ID suffix from voucher
function sv_wc_pdf_product_vouchers_remove_voucher_number_order( $number, $prefix, $random, $order_id ) {

	$voucher_number = ! empty( $prefix ) ? $prefix . '-' : '';
	$voucher_number .= $random;

	// always stop here and return the voucher number, regardless of whether order exists
	return $voucher_number;
}
add_filter( 'wc_pdf_product_vouchers_generated_voucher_number', 'sv_wc_pdf_product_vouchers_remove_voucher_number_order', 10, 4 );
If you wanted to filter the prefix more directly, also consider filtering the option (this option is currently unused by the plugin settings, but exists): pre_option_wc_pdf_product_vouchers_voucher_number_prefix This example snippet illustrates adding a prefix for voucher numbers.

wc_pdf_product_vouchers_get_{$field_id}

Filters the voucher field values.
@since
3.0.0
@param
mixed $value the field value
@param
\WC_Voucher $voucher the voucher object
Allows third parties to filter the value of the voucher field before the voucher is generated. Possible (core) field IDs: logo, voucher_number, product_name, product_sku, product_quantity For example, this could be used to append the product short description to the product name. This filter can also be used to set the value of custom voucher fields.

wc_pdf_product_vouchers_get_{$field_id}_formatted

Filters the voucher formatted field value.
@since
3.0.0
@param
mixed $formatted_value the formatted field value
@param
\WC_Voucher $voucher the voucher object
Allows third parties to filter the formatted value of the voucher field before the voucher is generated (what’s actually output). Possible (core) field IDs: logo, voucher_number, product_name, product_sku, product_quantity, expiration_date This filter can also be used to set the value of custom voucher fields.

wc_pdf_product_vouchers_get_expiry_days

Filters the number of days this voucher is valid for.
@since
3.0.0
@param
int $expiry expiry days
@param
\WC_Voucher $voucher the voucher object
Allows you to adjust expiration days, potentially to set a default expiration for all vouchers automatically, or based on order details by checking if the voucher has an associated order via $voucher->get_order()

Voucher Lifecycle

↑ Back to top
You can hook into the voucher lifecycle at several instances to fire third party code or adjust vouchers themselves.

Generated Voucher Actions

↑ Back to top

wc_pdf_product_vouchers_new_voucher_note

Fires after a new voucher note is added.
@since
3.0.0
@param
array $new_voucher_note_args voucher note arguments
@param
array $args {
  • @type int $voucher_id the voucher post ID
  • @type string $voucher_note the voucher note content
    • }

wc_pdf_product_vouchers_voucher_status_changed

Fires when voucher status is updated.
@since
3.0.0
@param
\WC_Voucher $voucher the voucher object
@param
string $old_status old status, without the wcpdf- prefix
@param
string $new_status new status, without the wcpdf- prefix
This can allow you to fire your own code when a voucher is activated, expired, redeemed, etc, or transitions between certain statuses.

wc_pdf_product_vouchers_generate_voucher_number

Fires when a voucher number is generated.
@since
1.2.0; v3.0.0 added $prefix, $random and $order_id params.
@param
string $number generated voucher number
@param
string $prefix voucher number prefix, if available
@param
string $random random part of the voucher number
@param
int $order_id order id associated with the voucher, if available
Note: This does not guarantee that a voucher with the generated number will be saved as-is (in case of duplication). Randomly generated numbers are checked for uniqueness before saving.

wc_pdf_product_vouchers_process_voucher_meta

Fires when a voucher is saved or updated from admin.
@since
3.0.0
@param
int $post_id post identifier
@param
\WP_Post $post the post object
Allows for saving custom voucher meta with post save.

wc_pdf_product_vouchers_voucher_created

Fires after a voucher has been created.
@since
3.0.0
@param
\WC_Voucher $voucher the voucher that was created

Frontend Hooks

↑ Back to top

Frontend Filters

↑ Back to top

wc_pdf_product_vouchers_customer_available_vouchers

Filters vouchers available for a customer.
@since
3.0.0
@param
\WC_Voucher[] $vouchers
@param
int $customer_id
This could be used, for example, to remove expired vouchers instead of showing all vouchers to a customer. 
// remove vouchers from My Account if they're expired
function sv_wc_pdf_product_vouchers_filter_customer_vouchers( $vouchers ) {

	foreach ( $vouchers as $id => $voucher ) {

		if ( $voucher->has_status( 'expired' ) ) {
			unset( $vouchers[ $id ] );
		}
	}

	return $vouchers;
}
add_filter( 'wc_pdf_product_vouchers_customer_available_vouchers', 'sv_wc_pdf_product_vouchers_filter_customer_vouchers' );

wc_pdf_product_vouchers_account_vouchers_actions

Filter the voucher actions under My Account > Vouchers.
@since
3.0.0
@param
array $actions as $key => $action (url + name)
@param
\WC_Voucher $voucher the voucher for that row
Allows for the addition of custom actions. Similar to “My Orders” actions.

wc_pdf_product_vouchers_account_vouchers_columns

Filter My Account > Vouchers columns.
@since
3.0.0
@param
array $columns the table column headers
Allows for the addition of custom columns.

Frontend Actions

↑ Back to top

wc_pdf_product_vouchers_before_account_vouchers

Fires before the “Vouchers” section under My Account > Vouchers.
@since
3.0.0
@param
bool $has_vouchers

wc_pdf_product_vouchers_after_available_vouchers

Fires after the available vouchers under My Account > Vouchers.
@since
3.0.0

wc_pdf_product_vouchers_after_account_vouchers

Fires after the “Vouchers” section under My Account > Vouchers.
@since
3.0.0
@param
bool $has_vouchers

wc_pdf_product_vouchers_account_vouchers_column_{$column_id}

Fires for a custom voucher column under My Account > Vouchers.
@since
3.0.0
@param
\WC_Voucher $voucher
If adding a custom column, the $column_id should match whatever has been added via the wc_pdf_product_vouchers_account_vouchers_columns filter. 
// add a new My Vouchers table header / column
function sv_wc_pdf_product_vouchers_custom_vouchers_column( $headers ) {

	$headers['recipient'] = 'For (Recipient)';

	return $headers;
}
add_filter( 'wc_pdf_product_vouchers_account_vouchers_columns', 'sv_wc_pdf_product_vouchers_custom_vouchers_column' );

// Add data for the new My Vouchers column
function sv_wc_pdf_product_vouchers_add_vouchers_column( $voucher ) {
	echo $voucher->get_recipient_name();
}
add_action( 'wc_pdf_product_vouchers_account_vouchers_column_recipient', 'sv_wc_pdf_product_vouchers_add_vouchers_column' );

Admin Hooks

↑ Back to top

Admin Filters

↑ Back to top

wc_pdf_prdouct_vouchers_voucher_search_fields

Filters the searchable fields when searching vouchers.
@since
3.0.0
@param
array $fields the voucher postmeta fields to search.

wc_pdf_product_vouchers_voucher_statuses

Filters available voucher statuses.
@since
3.0.0
@param
array $statuses associative array of statuses and labels
Allows for the addition of custom voucher statuses.

Methods and Global Functions

↑ Back to top

WC_Voucher

↑ Back to top
While we won’t list every method here, the WC_Voucher object is a good one to review, as this provides methods to get or set almost any piece of voucher data, or programmatically process redemptions, voids, etc. You can find this in: /includes/class-wc-voucher.php This also extends the abstract WC_Voucher_Base, which handles a couple lower-level functions that also apply to voucher templates, such as $voucher->get_id()

Conditional Checks

↑ Back to top
There are a few conditional checks that can help you determine voucher or product information.

WC_PDF_Product_Vouchers_Product::has_voucher_template( $product )

Returns true if the given product has an attached voucher template.
@since
3.0.0
@param
\WC_Product $product the product to check for a voucher
@return
boolean true if $product has a voucher, false otherwise
Here’s an example that creates a “true” sold-individually voucher. Since voucher meta always differs, the core “sold individually” setting won’t force the cart to have only “one” of a particular voucher product, so this checks if the product has a voucher template, then only forces a quantity of “1” in the cart.

$voucher->has_status( $status )

Checks the voucher status against a passed in status. Must use a WC_Voucher instance — not called statically.
@since
3.0.0
@param
string|array $status A status or array of statuses to test
@return
boolean true if the voucher has the tested status

$voucher->has_redemptions()

Checks if voucher has any redemptions. Must use a WC_Voucher instance — not called statically.
@since
3.0.0
@return
boolean true if the voucher has at least one redemption

Global & Static Functions

↑ Back to top

WC_PDF_Product_Vouchers_Product::get_voucher_template( $product )

Returns the voucher template attached to $product.
@since
3.0.0
@param
\WC_Product $product the product to check for a voucher
@return
\WC_Voucher_Template the voucher template attached to $product

WC_PDF_Product_Vouchers_Product::get_voucher_template_id( $product )

Returns the voucher id of the voucher template attached to $product, if any.
@since
3.0.0
@param
\WC_Product $product the product to check for a voucher
@return
int voucher id of attached voucher, if any

WC_PDF_Product_Vouchers_Order::get_vouchers( $order )

Returns any vouchers attached to an order.
@since
3.0.0
@param
\WC_Order $order the order object
@return
\WC_Voucher[]

WC_PDF_Product_Vouchers_Order::get_order_item_vouchers( $item )

Returns any vouchers associated with an order item.
@since
3.0.0
@param
\WC_Order_Item_Product|array $item order item
@return
\WC_Voucher[]

wc_pdf_product_vouchers_get_voucher( $post = null )

Returns a voucher object from ID, or post object.
@since
3.0.0
@param
int|\WP_Post|\WC_Voucher $post (optional) post object or post id of the voucher, defaults to global $post object
@return
\WC_Voucher|false

wc_pdf_product_vouchers_get_voucher_statuses()

Returns all voucher statuses
@since
3.0.0
@return
array

wc_pdf_product_vouchers_get_voucher_status_name( $status )

Returns the nice name for a voucher status slug.
@since
3.0.0
@param
string $status voucher status slug
@return
string voucher status name (label)

wc_pdf_product_vouchers_get_voucher_status_name( $status )

Returns the nice name for a voucher status slug.
@since
3.0.0
@param
string $status voucher status slug
@return
string voucher status name (label)

wc_pdf_product_vouchers_get_customer_available_vouchers( $customer_id = null )

Returns available vouchers for a customer.
@since
3.0.0
@param
int $customer_id (optional) user identifier, defaults to current user
@return
\WC_Voucher[]

wc_pdf_product_vouchers_create_voucher( $args = array() )

Programmatically creates a voucher. Returns a new WC_Voucher object on success which can then be used to add additional data, but will return WP_Error on failure.
@since
3.0.0
@param
array $args (see below)
@return
\WC_Voucher|\WP_Error
The arguments you can pass in to create a new voucher are as follows:
array key data type required value
number string – voucher number; defaults to a unqiue, generated voucher number
voucher_id int – voucher identifier; if provided, will perform an update instead of insert
voucher_template_id int required voucher template identifier
voucher_image_id int – voucher image identifier; defaults to the primary voucher image of the voucher template
currency string – voucher currency code; (ie USD) defaults to WooCommerce currency
user_id int – voucher customer identifier
product_id int – voucher product identifier
product_price int – voucher product price; defaults to the order item or the product price
product_quantity int – voucher product quantity; defaults to 1
order_item_id int – order item id this voucher is related to
date string – voucher date in mysql format; defaults to now

Creating Custom Voucher Fields

↑ Back to top
Check out this step-by-step guide to custom voucher fields as well.
To customize the voucher output, you can customize the HTML template, or add your own custom fields to the voucher. To customize the voucher HTML template, copy woocommerce-pdf-product-vouchers/templates/voucher/voucher.php to your theme: my-theme/voucher/voucher.php and customize it to your needs. Note: this template is used by both the voucher template and the generated vouchers. To add custom fields to a voucher, you’ll need to leverage a few hooks:

wc_pdf_product_vouchers_voucher_fields

Filters the voucher fields.
@since
3.0.0
@param
array $fields associative array of voucher fields
Along with the wc_pdf_product_vouchers_get_{$field_id} and wc_pdf_product_vouchers_get_{$field_id}_formatted filters, which will apply to your new field ID. These filters are only needed for property-type fields. Custom voucher fields can have a data_type = “property” or “user_input”. A property data type is static for each voucher, while a user input allows for customer input on the product page. A “property” type field muse be filtered to set its value and formatted value for pdf generation. You can use the voucher object to set properties for this. For example, $voucher->get_order_item() will give you the order item, which can be used to output voucher values. “User input” type fields can be generated from customer input on the product page. Here’s an example of adding both field types to a vouchers. These fields can then be included in the voucher templates output and / or settings.

User Documentation

↑ Back to top
Return to user documentation →
Use of your personal data
We and our partners process your personal data (such as browsing data, IP Addresses, cookie information, and other unique identifiers) based on your consent and/or our legitimate interest to optimize our website, marketing activities, and your user experience.