Coupons by User Role: Developer Hooks and Filters Reference

Developer hooks and filters reference #

Coupon by User Role for WooCommerce exposes a small set of filters so you can extend role matching in code, for example to add a synthetic role or override which roles a rule targets. Every filter below is called from the plugin’s own logic, so what you return replaces the value the settings screen would produce.

Filters #

WooCommerce filters the plugin hooks #

Coupon by User Role does its work through WooCommerce’s own coupon filters, all attached at PHP_INT_MAX so they run last. Knowing these helps when debugging interactions with other coupon plugins:

• woocommerce_coupons_enabled: returns false to hide the coupon field for a disabled role.
• woocommerce_coupon_is_valid: throws an exception with error code 10000 to invalidate a coupon for a role.
• woocommerce_coupon_error: swaps in the custom “Coupon is not valid” message for that error code.
• woocommerce_coupon_get_amount: returns the per-role amount for the current user.

Example: add a synthetic “wholesale” role to the selectors #

add_filter( 'alg_wc_cbur_user_roles', function ( $roles ) {
    $roles['wholesale_customer'] = 'Wholesale Customer';
    return $roles;
} );

In the free version the selectors list the eight standard roles only. Adding a key here makes it selectable in the settings. Custom roles are included automatically in the Pro version, so this is mainly useful for synthetic or virtual roles.

Example: invalidate every coupon for a role, in code #

add_filter( 'alg_wc_cbur_invalid_user_roles', function ( $roles, $coupon, $type ) {
    if ( 'exceptions' === $type ) {
        return $roles; // leave the exceptions list untouched
    }
    $roles[] = 'wholesale_customer';
    return array_unique( $roles );
}, 10, 3 );

Always check $type first: the same filter supplies both the invalid roles and their exceptions, and you rarely want to change both.

Example: exempt a role from the disable rule #

add_filter( 'alg_wc_cbur_disabled_user_roles', function ( $roles ) {
    return array_values( array_diff( $roles, array( 'subscriber' ) ) );
} );

Notes for integrators #

• Logged-out visitors resolve to the role key guest. Include it in your arrays to affect them.
• A rule matches when the user has one of the target roles and none of the exception roles, so exceptions are evaluated as a subtraction, not a separate pass.
• Stored option and meta keys use legacy prefixes (wpjup_wc_coupon_by_user_role_*, alg_wc_coupon_by_user_role_*). Read them exactly as written; they are not renamed at runtime.
• The plugin declares HPOS (High-Performance Order Storage) compatibility, so callbacks can run on stores using custom order tables.

Need a hand? #

Our team answers developer questions on the Coupon by User Role support forum.