Try for free

How can we help?

Search the documentation or ask the AI agent anything about the plugin.

Developers: Code Snippets & Resources

Updated October 20, 2026

The REST API is wcusage/v2. Enable it under Coupon Affiliates > API, Webhooks & AI > REST API, then see API, Webhooks & AI for merchant setup (keys, scopes, webhooks) and the API documentation for authentication, routes, payloads and examples. For connecting AI apps over MCP, see AI & MCP.

Below are PHP snippets and resources that customers have asked for. They are not a substitute for the REST API reference.

Database Tables

The plugin does have its own database tables that you can get certain data from:

wcusage_activity – Activity log.

wcusage_api_keys – REST API keys (hashed), with their scopes, status and last-used date.

wcusage_campaigns – Referral URL campaigns.

wcusage_clicks – Referral URL clicks log.

wcusage_directlinks – Direct link tracking domains.

wcusage_mlainvites – Multi-Level affiliates invites.

wcusage_payouts – Commission Payouts

wcusage_register – Affiliate registration applications.

wcusage_rewards_log – Log of performance bonuses (rewards) earned by affiliates, including the reward name, requirement met and bonuses granted.

Webhooks are not stored in a table; they are saved in the wcusage_api_webhooks option. The AI & MCP settings are saved in the wcusage_api_settings option, and the “Recent AI activity” list in the wcusage_abilities_log option.

Affiliate Orders

Get all affiliate orders for a coupon, without certain data range. This returns an array of data including the total calculations for all the orders, and all the individual orders.

$orders = wcusage_wh_getOrderbyCouponCode( $coupon_code, $start_date, $end_date, '', 1 );

Order Data

You can get an array of affiliate related data for a certain order via this function. This returns an array of data including the commission earnings.

$order_data = wcusage_calculate_order_data( $order_id, $coupon_code, 0, 1 );

To get the commission from the order for example:

$commission = $order_data['totalcommission'];

Affiliate URL

Get the affiliate URL for a coupon via the following function:

$coupon_code = ""; // Set the coupon code name here.
$affiliate_url = wcusage_get_affiliate_url($coupon_code);

Or if you want to build your own custom URL here’s an example:

$coupon_code = ""; // Set the coupon code name here.
$prefix = wcusage_get_setting_value('wcusage_field_urls_prefix', 'coupon');
$affiliate_url = get_home_url() . "?" . $prefix . "=" . $coupon_code;

Hook (Filter): Change the Referral URL

Every affiliate link is built from a base URL, which comes from the “Default Referral URL Page” setting. That setting is corrected back to your WordPress domain whenever the two disagree, so that a URL left behind by a site migration repairs itself rather than sending your affiliates to a domain the shop no longer owns.

If you deliberately serve your shop from a different domain to the WordPress install – a separate front end or a headless setup, for example – use the “wcusage_default_ref_url” filter rather than the setting:

add_filter( 'wcusage_default_ref_url', function( $url ) {
    return 'https://shop.example.com/';
} );

The URL you return is used exactly as given, so include a trailing slash (or a path) if you want one. It is not checked against your site’s own domain, on the understanding that requests to it have to reach your site for referrals to be tracked.

This filter covers the affiliate dashboard, the referral URL generator, the social share buttons, QR codes, creatives, the affiliate widget, the referral URL shortcodes and the registration emails.

To replace a whole link instead – a vanity or shortened link, for example – use the “wcusage_affiliate_url” filter, which runs after the coupon code has been added:

add_filter( 'wcusage_affiliate_url', function( $affiliate_url, $coupon_code ) {
    return 'https://go.example.com/' . rawurlencode( $coupon_code );
}, 10, 2 );

This one covers the affiliate dashboard, QR codes, creatives, the referral URL shortcodes and the registration emails.

Recording Referral Clicks from a Custom Front End

If your referral links are handled outside of WordPress – a headless or decoupled front end, for example – you can record the click yourself, so that it still reaches the affiliate’s URL statistics. Use the “wcusage_record_click()” function:

$click_id = wcusage_record_click( $coupon_code, array(
    'campaign'  => '',   // Campaign / "src" value.
    'page'      => 0,    // Post ID of the landing page. 0 shows as the homepage.
    'referrer'  => '',   // A full URL or a domain. Only the domain is stored.
    'ip'        => null, // Visitor IP, or an ID of up to 64 characters.
    'converted' => false,
) );

It returns the ID of the click it saved, or false if the coupon was not found, the referrer is one of your blocked domains, or the click could not be saved.

  • The first parameter is a coupon code, or a coupon ID.
  • Setting ‘ip’ to null detects it from the current request the way the plugin’s own tracking does, which is only meaningful when the visitor’s browser is what made the request.
  • Unlike the plugin’s own tracking, this does no throttling. If your front end can be hit more than once for the same visit (bots, prefetching, a page refresh) you should decide for yourself whether a visit is a new click before calling it.

A “wcusage_click_recorded” action fires afterwards, passing the click ID, the coupon ID, and the details the click was recorded with.

Marking the conversion

Conversions are normally matched using a cookie set when the visitor follows the referral link, which a front end recording its own clicks has no way to set. Keep hold of the click ID returned above – saved against the order, for example – and hand it back with the “wcusage_conversion_click_id” filter:

add_filter( 'wcusage_conversion_click_id', function( $click_id, $order_id ) {
    return get_post_meta( $order_id, 'my_referral_click_id', true );
}, 10, 2 );

Return an empty value to leave the order unattributed. Note that this filter runs where the plugin marks conversions, on the WooCommerce order received page, so a front end that never loads that page will need to mark the conversion itself.

Total Sales and Commission

Get the total sales and commission earned by a certain coupon, without a certain date range. Leave $start_date empty to get all sales.

$orders = wcusage_wh_getOrderbyCouponCode( $coupon_code, $start_date, $end_date, '', 1 );
$total_orders = $orders['total_orders']; // Total Sales
$total_discounts = $orders['full_discount']; // Total Discounts
$total_commission = $orders['total_commission']; // Total Commission
$order_count = $orders['total_count']; // Orders Count

Unpaid Commission

Get the total unpaid commission for an affiliate coupon.

$coupon_id = ""; // Set the coupon code ID here.
$unpaid_commission = get_post_meta( $coupon_id, 'wcu_text_unpaid_commission', true );

Hook (Action): New Affiliate Registration Submitted

When there is a new affiliate registration, it will run the “wcusage_hook_registration_new” hook that will pass the registration ID, user ID, and coupon code.

You could therefore call this hook to automatically accept the registration under certain conditions with the “wcusage_set_registration_status” function. For example this will automatically accept the registration if the users role is “example”:

add_action( 'wcusage_hook_registration_new', 'trigger_wcusage_hook_registration_new', 10, 3 );
function trigger_wcusage_hook_registration_new( $registration_id, $user_id, $coupon_code ) {
    $user_info = get_userdata( $user_id );
    $roles = $user_info->roles;

    if ( in_array( 'example', $roles ) ) {
        wcusage_set_registration_status( 'accepted', $registration_id, $user_id, $coupon_code, '', '' );
    }
}

Hook (Action): New Affiliate Accepted

When a new affiliate is accepted and added to your program, it will run the “wcusage_hook_affiliate_register_accepted” that will pass the following:

  • $id – Registration ID.
  • $userid – User ID.
  • $coupon_code – Coupon Code.
  • $message – The registration acceptance message.
  • $status – The status of their registration.
add_action( 'wcusage_hook_affiliate_register_accepted', 'trigger_wcusage_hook_registration_accepted', 10, 5 );
function trigger_wcusage_hook_registration_accepted( $id, $userid, $coupon_code, $message, $status ) {
// Your code here.
}

Hook (Action): Trigger a Performance Bonus from a Custom Event (PRO)

Performance Bonuses can be triggered from your own theme or plugin code. When creating a bonus, set the trigger type to “Developers: Custom Event / Action” and enter a Custom Event Key. Then fire the “wcusage_custom_event” action with that same key whenever the event happens:

do_action( 'wcusage_custom_event', 'your_event_key', $user_id );
// Or target a specific affiliate coupon:
do_action( 'wcusage_custom_event', 'your_event_key', $user_id, array(), 'COUPONCODE' );
  • ‘your_event_key’ must match the Custom Event Key entered on the bonus.
  • $user_id is the WordPress user ID of the affiliate to reward.
  • The fourth parameter (optional) is a coupon code or coupon post ID to target a specific affiliate coupon. When omitted, all coupons belonging to the user are checked.

See (PRO) Performance Bonuses for how to set up the bonus itself.

Hooks (Filters): AI & MCP Abilities

From version 8.6.0, Coupon Affiliates registers its abilities with the WordPress Abilities API (WordPress 6.9 or later), for AI apps and other plugins to use. See AI & MCP for the settings. Abilities are named coupon-affiliates/<name>, for example coupon-affiliates/list-affiliates, and other plugins can run them directly with the Abilities API, without MCP.

Use the “wcusage_abilities_definitions” filter to add, change or remove abilities. It receives an array of ability name => definition. For example, to remove one:

add_filter( 'wcusage_abilities_definitions', function( $definitions ) {
    unset( $definitions['coupon-affiliates/list-activity'] );
    return $definitions;
} );

Each definition needs a label, description, controller, permission and callback (the controller class, its permission method and its handler method). Optional keys include group, type (“read” or “write”), destructive, idempotent, access (“admin”, or “affiliate” when an affiliate may call it for their own data), and the input and output JSON schemas. Definitions missing a required key are dropped. The full list of keys is documented in inc/abilities/abilities-definitions.php.

The “wcusage_abilities_rate_limit” filter sets how many calls each user can make per minute, counted separately for reads and writes (default 120 reads and 20 writes). Return 0 or less to switch the limit off:

add_filter( 'wcusage_abilities_rate_limit', function( $limit, $type, $user_id ) {
    return ( 'write' === $type ) ? 10 : $limit;
}, 10, 3 );

Other filters:

  • wcusage_abilities_controller_files – class name => file path, for the controller classes your own abilities call.
  • wcusage_abilities_log_size – how many calls “Recent AI activity” keeps (default 30). Return 0 to switch the log off.
  • wcusage_abilities_mcp_server_enabled – return false to skip the dedicated “Coupon Affiliates” MCP server, leaving the abilities on the MCP Adapter’s default server only.
  • wcusage_abilities_show_notice – whether to show the admin notice offering to enable the AI tools.
  • wcusage_abilities_connector_plugins – the MCP connector plugins suggested on the AI & MCP tab, as WordPress.org slug => array( name, note ).
  • wcusage_abilities_connector_gaps – abilities a connector plugin is not sharing, as plugin name => array( 'url' => its abilities screen, 'missing' => ability names ), shown as a warning on the tab.
  • wcusage_abilities_request_channel – how a call is recorded in “Recent AI activity” (“mcp”, “rest”, “cli” or “php”), passed the channel and the REST route. Useful for an MCP server whose route does not contain “mcp”.
  • wcusage_api_admin_handle_action – handles your own form actions on the API, Webhooks & AI screen. It runs after the nonce and capability checks, and is passed the redirect URL and the submitted action; return where to redirect.

Hooks: Affiliate Suspension

From version 8.4.0, affiliates can be suspended instead of deleted. See Suspending an Affiliate for how it works. To check whether an affiliate is suspended in your own code:

if ( wcusage_is_affiliate_suspended( $user_id ) ) {
    // The affiliate is suspended.
}

// Or for a coupon (true when the affiliate assigned to it is suspended):
if ( wcusage_is_coupon_suspended( $coupon_id ) ) {
    // The coupon is locked.
}

The “wcusage_hook_affiliate_suspended” and “wcusage_hook_affiliate_unsuspended” actions run when an affiliate is suspended or the suspension is lifted, and pass the user ID:

add_action( 'wcusage_hook_affiliate_suspended', function( $user_id ) {
    // Your code here.
} );

Filters:

  • wcusage_is_affiliate_suspended – whether an affiliate counts as suspended, passed the saved value and the user ID.
  • wcusage_hook_suspended_coupon_error – the message shown when someone tries to use a suspended affiliate’s coupon (default “Sorry, this coupon is no longer available.”).
  • wcusage_hook_suspended_dashboard_notice – the HTML of the notice a suspended affiliate sees in place of their dashboard.
  • wcusage_hook_suspended_shortcodes_allowed – the shortcodes that still display for a suspended affiliate (default “couponaffiliates-register” and “couponaffiliates-leaderboard”).

Legacy v1 API

The original three endpoints under woo-coupon-usage/v1 are still registered for existing integrations. They require a WordPress administrator role. They are not the current API. New integrations should use wcusage/v2.

GET /wp-json/woo-coupon-usage/v1/coupon-info with coupon_id. Returns coupon_name, unpaid_commission, and pending_payouts.

GET /wp-json/woo-coupon-usage/v1/users-coupons with user (the login name). Returns coupon IDs assigned to that user, with unpaid commission.

POST /wp-json/woo-coupon-usage/v1/request-payout with coupon_id and user (login). Returns 1 on success or 0 on failure. PRO.

Need help with a custom function? Feel free to contact us and we may be able to point you in the right direction.

Was this article helpful?