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 topWooCommerce 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 topPost 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 topPost 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 topTo 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 topFiltering Voucher Data
↑ Back to topwc_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 topwc_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 topYou can hook into the voucher lifecycle at several instances to fire third party code or adjust vouchers themselves.
Generated Voucher Actions
↑ Back to topwc_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 topFrontend Filters
↑ Back to topwc_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 topwc_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 topAdmin Filters
↑ Back to topwc_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 topWC_Voucher
↑ Back to topWhile 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 topThere 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 topWC_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 topCheck 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.
