Featured-Upgrade Credit Consumer

Some employers want to post a regular job today and upgrade it to Featured later - promoting it to the top of search results, homepage spotlight, and sidebar widgets. The featured-upgrade consumer lets that upgrade spend credits separately from the original posting cost.

Scope: Pro registers the featured_upgrade consumer and wires the full hold -> deduct / refund cycle to the hooks below. It does not ship a built-in “Make Featured” button in the dashboard - the upgrade runs when something fires wcb_featured_upgrade_requested (for example a custom button, an addon, or another integration). The machinery is in place so the charge is handled correctly when that trigger exists.

How it works

Pro registers a second consumer with the Credits SDK:

Consumer slug	Hooks	Cost option
featured_upgrade	hold: wcb_featured_upgrade_requested deduct: wcb_featured_upgrade_completed refund: wcb_featured_upgrade_failed	wcbp_featured_upgrade_cost (default 10)

The full hold -> deduct / refund cycle runs the same way as for posting a new job. If the upgrade fails (the job is in the wrong status, or the employer cancels mid-flow), the credits return to their balance.

Pairs with Free’s daily expiry cron

Free 1.1.0 ships a daily cron that auto-clears the _wcb_featured post-meta after the configured duration (apply_featured_days, default 30 days). So a featured upgrade is time-bounded - when the boost expires, the employer can pay credits again to refresh the boost.

This makes the featured-upgrade economy work like a recurring revenue line: the same job can spend credits multiple times over its life.

Setting the cost

Set the global cost via WP-CLI or the Settings UI:

wp option update wcbp_featured_upgrade_cost 15

The cost is filtered through wcbp_consumer_cost, so the same tiered pricing matrix that discounts job posting also discounts featured upgrades. A “premium” PMPro level can upgrade for free even if everyone else pays 15 credits.

Triggering the upgrade

The consumer charges credits when these hooks fire (it does not ship a ready-made button):

• Fire wcb_featured_upgrade_requested with the job ID to hold the cost.
• Fire wcb_featured_upgrade_completed to deduct (the upgrade succeeded).
• Fire wcb_featured_upgrade_failed to refund (the upgrade was cancelled or the job was in the wrong status).

A custom dashboard button, an addon, or another integration wires these hooks to its own UI. When the trigger runs, the hold -> deduct / refund cycle is handled for you, including tier pricing. See the Pro hooks reference for the exact signatures.

Disabling the consumer

If you want featured strictly free or strictly admin-set (not credit-bought):

add_filter( 'wcbp_consumer_cost', function ( $cost, $user_id, $item_id, $board_id, $consumer ) {
    return 'featured_upgrade' === $consumer ? 0 : $cost;
}, 99, 5 );

Returning 0 skips the hold/deduct cycle entirely - the upgrade proceeds without touching the ledger.