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 #
| Filter | Arguments | Purpose |
|---|---|---|
alg_wc_cbur_user_roles |
$roles (associative array of role_key => label) |
Change which roles appear in every role selector. This is how Pro injects all custom roles. |
alg_wc_cbur_disabled_user_roles |
$disabled_user_roles (array of role keys) |
Add or remove roles from the “disable all coupons” set at runtime. |
alg_wc_cbur_invalid_user_roles |
$invalid_user_roles, $coupon, $type |
Adjust the “invalidate” set for a coupon. Fired twice: once for the invalid roles ($type empty) and once for the exceptions ($type is 'exceptions'). This is the hook the per-coupon tab uses. |
alg_wc_cbur_settings |
$value, $type, $args |
Filters the settings notes block. Pro uses it to remove the free-version upsell notice. |
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: returnsfalseto hide the coupon field for a disabled role.woocommerce_coupon_is_valid: throws an exception with error code10000to 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 #
Coupon by User Role for WooCommerce
Get more from Coupon by User Role for WooCommerce
See every feature and the pricing on the Coupon by User Role for WooCommerce plugin page.
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.