---
title: "Coupons by User Role: Developer Hooks and Filters Reference"
description: "Developer reference for Coupon by User Role for WooCommerce: filters to extend role matching, with a synthetic role example."
url: "https://wpfactory.com/docs/coupon-by-user-role-hooks-filters/"
updated: "2026-09-26"
category: Developers
---

# Coupons by User Role: Developer Hooks and Filters Reference

## Developer hooks and filters reference

[Coupon by User Role for WooCommerce](https://wpfactory.com/item/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`: 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](https://wpfactory.com/support/item/coupon-by-user-role-for-woocommerce/).

Related articles

- [Coupons by User Role: How to Reset a Settings Section](https://wpfactory.com/docs/reset-coupon-settings-section/)
- [Free vs Pro: Coupon by User Role for WooCommerce](https://wpfactory.com/docs/free-vs-pro/)
- [How Coupon Validation by User Role Works](https://wpfactory.com/docs/coupons-apply/)
- [One Coupon, Different Discount Amounts per User Role](https://wpfactory.com/docs/setting-role-based-discounts/)
- [How to Disable or Invalidate WooCommerce Coupons by User Role](https://wpfactory.com/docs/effortless-targeted-promotions/)