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.

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

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 →