WooCommerce Checkout Add-ons Developer Docs

Please be aware that this document is meant for developers. We do not support or do plugin customizations as per our support policy.

If you need help changing this code or extending it, we recommend using a Woo Expert or customization service, such as Codeable or Envato Studios.

Overview ↑ Back to top

Checkout Add-ons will add order fees for WooCommerce orders. These fee items are added as order line items, so you could access this data via the order line items.

At checkout, add-ons use core WooCommerce fields. By default, WooCommerce uses the following attributes for fields:

$defaults = array(
    'type'              => 'text',
    'label'             => '',
    'description'       => '',
    'placeholder'       => '',
    'maxlength'         => false,
    'required'          => false,
    'id'                => $key,
    'class'             => array(),
    'label_class'       => array(),
    'input_class'       => array(),
    'return'            => false,
    'options'           => array(),
    'custom_attributes' => array(),
    'validate'          => array(),
    'default'           => '',

You can add custom attributes by adding an array of attributes, or changing these defaults. Please note that you should not change the “type” attribute for a checkout add-on. To make any adjustments, you’ll need the checkout add-on id, which can be found by viewing add-ons:

WooCommerce Checkout Add-ons id

You can then target the checkout add-on id to add attributes or change defaults.


Changing Checkout Add-ons Attributes ↑ Back to top

You can change attributes, such as the maxlength or description, by using something like this:

This will add your attributes to the checkout fields:

WooCommerce checkout add-ons

Note that there was a bug with the maxlength attribute for textareas that was patched in WooCommerce 2.2.5, so you’ll need to run at least this version to use maxlengths for textareas.


Move Checkout Add-on Location ↑ Back to top

By default, add-ons are displayed after the billing details at checkout. You have limited ability to move the add-ons in the plugin settings, and have more fine-grained control via the wc_checkout_add_ons_position filter, which can accept a different action on the checkout page:


Conditionally Display Add-ons ↑ Back to top

Sometimes users only want to display checkout add-ons as “gift” options. Here’s a snippet that will hide or show checkout add-ons based on the shipping address. If the shipping address is the same as billing, the fields will be hidden. If shipping differs from the billing address, the gift add-on fields will be shown.

Note that this should not be used with required add-ons, as customers won’t be able to complete the field if it’s hidden. These add-ons should always be optional.

You can also use your own code to determine when add-ons will be shown, and conditionally remove them using:

$position = apply_filters( 'wc_checkout_add_ons_position', get_option( 'wc_checkout_add_ons_position', 'woocommerce_checkout_after_customer_details' ) );
remove_action( $position, array( wc_checkout_add_ons()->frontend, 'render_add_ons' ) );

For example, you could remove add-ons if any product in the cart is in a particular category:

Or you could remove add-ons only if all products in the cart are in the category:

User Docs ↑ Back to top

Return to the user documentation →

WooCommerce - the most customizable eCommerce platform for building your online business.

Back to the top