WooCommerce Code Reference

WC_Admin_Marketplace_Promotions
in package

WC_Admin_Marketplace_Promotions class.

Table of Contents

CRON_NAME  = 'woocommerce_marketplace_cron_fetch_promotions'
DISMISSED_PROMOS_META  = '_wc_marketplace_dismissed_promos'
PROMOTIONS_API_URL  = 'https://woocommerce.com/wp-json/wccom-extensions/3.0/promotions'
RULE_BASED_FORMAT  = 'rule-based-promo-card'
TRANSIENT_LIFE_SPAN  = DAY_IN_SECONDS
TRANSIENT_NAME  = 'woocommerce_marketplace_promotions_v2'
$locale  : string
The user's locale, for example en_US.
$orders_promo_card  : array<string|int, mixed>|null
Request-scoped cache of the eligible Orders-screen promo card (or null).
$orders_promo_card_resolved  : bool
Whether the Orders-screen promo card has been resolved this request.
clear_cron_event()  : void
When WooCommerce is disabled, clear the WP Cron event we use to fetch promotions.
clear_deprecated_action()  : mixed
We can't clear deprecated action from AS when it's running, so we schedule a new single action to clear the deprecated `woocommerce_marketplace_fetch_promotions` action.
clear_deprecated_scheduled_event()  : void
Clear deprecated scheduled action that was used to fetch promotions in WooCommerce 8.8.
filter_marketplace_menu_items()  : array<string|int, mixed>
Callback for the `woocommerce_marketplace_menu_items` filter in `Automattic\WooCommerce\Internal\Admin\Marketplace::get_marketplace_pages`.
get_active_promotions()  : mixed
Get active Marketplace promotions from the transient.
init()  : void
On all admin pages, try go get Marketplace promotions every day.
maybe_enqueue_orders_promo_card()  : void
Enqueue the Orders-screen promo card script and localize the resolved promo.
update_promotions()  : void
Fetch promotions from the API and store them in a transient.
append_bubble()  : string
Return the markup for a menu item bubble with a given text.
fetch_marketplace_promotions()  : array<string|int, mixed>
Get promotions to show in the Woo in-app marketplace and load them into a transient with a 12-hour life. Run as a recurring scheduled action.
filter_out_inactive_promotions()  : array<string|int, mixed>
Find promotions that are still active – they have a date range that includes the current date.
get_dismissed_promo_ids()  : array<string|int, string>
Get the promo ids the current user has permanently dismissed.
get_promotions_of_format()  : array<string|int, mixed>
From the array of promotions, select those of a given format.
is_orders_screen()  : bool
Whether the current screen is the WooCommerce Orders list (HPOS or legacy).
maybe_show_bubble_promotions()  : void
If there's an active promotion of the format `menu_bubble`, add a filter to show a bubble on the Extensions item in the WooCommerce menu.
merge_promos()  : array<string|int, mixed>
Promos arrive in the array of promotions as an array of arrays with the key 'promos'.
promotion_rules_pass()  : bool
Evaluate local_rules using the WooCommerce Admin remote specs rule schema.
promotion_targets_orders()  : bool
Whether a promotion declares the Orders screen as a placement, via a `pages` entry of `{ "page": "wc-orders" }`.
resolve_rule_based_promotions()  : array<string|int, mixed>
Evaluate locally targeted promotions before they are exposed to JS.
rules_are_valid()  : bool
Recursively validate a rule (or array of rules) before evaluation.
schedule_cron_event()  : void
Schedule a daily cron event to fetch promotions.

Constants

Properties

Methods

clear_deprecated_action()

We can't clear deprecated action from AS when it's running, so we schedule a new single action to clear the deprecated `woocommerce_marketplace_fetch_promotions` action.

public static clear_deprecated_action() : mixed
Return values
mixed —

clear_deprecated_scheduled_event()

Clear deprecated scheduled action that was used to fetch promotions in WooCommerce 8.8.

public static clear_deprecated_scheduled_event() : void

Replaced with a transient in WooCommerce 9.0.

Return values
void —

filter_marketplace_menu_items()

Callback for the `woocommerce_marketplace_menu_items` filter in `Automattic\WooCommerce\Internal\Admin\Marketplace::get_marketplace_pages`.

public static filter_marketplace_menu_items(array<string|int, mixed> $menu_items[, array<string|int, mixed>|null $promotion = array() ]) : array<string|int, mixed>

At the moment, the Extensions page is the only page in $menu_items. Adds a bubble to the menu item.

Parameters
$menu_items : array<string|int, mixed>

Arrays representing items in nav menu.

$promotion : array<string|int, mixed>|null = array()

Data about a promotion from the WooCommerce.com API.

Return values
array<string|int, mixed> —

get_active_promotions()

Get active Marketplace promotions from the transient.

public static get_active_promotions() : mixed

Use woocommerce_marketplace_suppress_promotions filter to suppress promotions.

Tags
since
9.0
Return values
mixed —

init()

On all admin pages, try go get Marketplace promotions every day.

public static init() : void

Shows notice and adds menu badge to WooCommerce Extensions item if the promotions API requests them.

WC_Admin calls this method when it is instantiated during is_admin requests.

Return values
void —

maybe_enqueue_orders_promo_card()

Enqueue the Orders-screen promo card script and localize the resolved promo.

public static maybe_enqueue_orders_promo_card() : void

The Orders list is a classic admin page, so the card is mounted by a wp-admin-scripts entry that inserts it above the orders table (see ShippingLabelBanner for the same enqueue pattern). The promotion is rule-resolved server-side and passed to the script, so no additional data is shared with WooCommerce.com.

Tags
since
11.0.0
Return values
void —

append_bubble()

Return the markup for a menu item bubble with a given text.

private static append_bubble(string $menu_item_text, string $bubble_text) : string
Parameters
$menu_item_text : string

Text of menu item we want to change.

$bubble_text : string

Text of bubble.

Return values
string —

fetch_marketplace_promotions()

Get promotions to show in the Woo in-app marketplace and load them into a transient with a 12-hour life. Run as a recurring scheduled action.

private static fetch_marketplace_promotions() : array<string|int, mixed>
Return values
array<string|int, mixed> —

filter_out_inactive_promotions()

Find promotions that are still active – they have a date range that includes the current date.

private static filter_out_inactive_promotions([array<string|int, mixed>|null $promotions = array() ]) : array<string|int, mixed>
Parameters
$promotions : array<string|int, mixed>|null = array()

Data about current promotions.

Return values
array<string|int, mixed> —

get_promotions_of_format()

From the array of promotions, select those of a given format.

private static get_promotions_of_format([array<string|int, mixed>|null $promotions = array() ][, string|null $format = '' ]) : array<string|int, mixed>
Parameters
$promotions : array<string|int, mixed>|null = array()

Array of data about promotions of all formats.

$format : string|null = ''

Format we want to filter for.

Return values
array<string|int, mixed> —

maybe_show_bubble_promotions()

If there's an active promotion of the format `menu_bubble`, add a filter to show a bubble on the Extensions item in the WooCommerce menu.

private static maybe_show_bubble_promotions() : void

Use woocommerce_marketplace_suppress_promotions filter to suppress the bubble.

Tags
throws
Exception

If we are unable to create a DateTime from the date_to_gmt.

Return values
void —

merge_promos()

Promos arrive in the array of promotions as an array of arrays with the key 'promos'.

private static merge_promos([array<string|int, mixed>|null $promotions = array() ]) : array<string|int, mixed>

We merge them into the main array.

Parameters
$promotions : array<string|int, mixed>|null = array()

Promotions data received from WCCOM. May have an element with the key 'promos', which contains an array.

Return values
array<string|int, mixed> —

promotion_rules_pass()

Evaluate local_rules using the WooCommerce Admin remote specs rule schema.

private static promotion_rules_pass(mixed $rules) : bool

WCCOM payloads must provide rules compatible with the existing Core rule processors. Unknown or malformed rules fail closed.

Parameters
$rules : mixed

Rule definitions from the promotions payload.

Return values
bool —

promotion_targets_orders()

Whether a promotion declares the Orders screen as a placement, via a `pages` entry of `{ "page": "wc-orders" }`.

private static promotion_targets_orders(array<string|int, mixed> $promotion) : bool
Parameters
$promotion : array<string|int, mixed>

The promotion definition.

Return values
bool —

resolve_rule_based_promotions()

Evaluate locally targeted promotions before they are exposed to JS.

private static resolve_rule_based_promotions(array<string|int, mixed> $promotions) : array<string|int, mixed>

Supported stores convert matching rule-based promos into standard promo cards. Unsupported stores ignore the custom format entirely.

Parameters
$promotions : array<string|int, mixed>

Promotions data received from WCCOM.

Return values
array<string|int, mixed> —

rules_are_valid()

Recursively validate a rule (or array of rules) before evaluation.

private static rules_are_valid(mixed $rules) : bool

Validation must cover nested not/or operands: an empty or malformed operand evaluates to false, and not would then flip that to true, showing the promo on a malformed payload. Unknown rule types resolve to a fail processor (which validates but always fails), so they are rejected here too. Anything not well-formed fails closed.

Parameters
$rules : mixed

A decoded rule object or array of rule objects.

Return values
bool —