Hooks reference · Siteryn AI Product Recommendations Docs

Engine

Hook	Arguments	Use
`…_strategy`	`$strategy, Context $c`	Replace or wrap the ranking strategy
`…_candidates`	`$candidates, $source_ids`	Add or remove candidates (also sent to the AI)
`…_rule_score`	`$score, $product, Context $c`	Adjust a rule-based score
`…_results`	`$ids, Context $c`	Reorder, remove or add products (re-validated afterwards)
`…_is_recommendable`	`$ok, $product`	Exclude products everywhere, including cached lists and AI picks
`…_schedule_ranking`	`$schedule, Context $c`	Stop a placement from queueing AI rankings
`…_ranking_generated` (action)	`$product_id, $ranking`	After an AI ranking is saved

AI

Hook	Arguments	Use
`…_providers`	`$providers`	Register providers
`…_provider_config`	`ProviderConfig`	The config used for rankings
`…_prompt_payload`	`$payload, $source`	The product data sent (`source`, `candidates`, `max_items`)
`…_system_prompt`	`$system, $version`	The system instructions
`…_max_retries`	`$retries, $provider_id`	0–2 retries
`…_allow_private_endpoint` · `…_allow_insecure_local_endpoint`	`$allow, $url`	Self-hosted models

Rendering & templates

Hook	Arguments	Use
`…_product_page_position`	`{hook, priority}`	Move the product page list
`…_placement_args`	`$args, $placement`	The product page list's `limit` (1–24), `title`, `columns`, `columns_tablet` (1–4), `columns_mobile` (1–2), `class`, `layout` (`grid` or `compact`) and `title_align`
`…_template_args`	`$args, Context $c`	Variables passed to the list template
`…_html`	`$html, Context $c, $ids`	The final list HTML
`…_card_button_attributes`	`$attrs, $product, $placement`	Attributes on the card's add to cart button
`…_card_after_body` (action)	`$product, $placement, $layout`	Add content to cards
`…_locate_template`	`$template, $template_name`	The template file used (theme copy or bundled)
`…_before_template` · `…_after_template` (actions)	`$template_name, $args`	Output around each template
`…_bundled_templates`	`$templates`	Templates checked for outdated theme copies

Lifecycle & settings

…_loaded, …_upgrade, …_deactivate (actions); …_settings_get_all, …_settings_sections, …_settings_fields, …_render_field_{type}, …_sanitize_field_{type}, …_settings_save_redirect, …_settings_reset_actions, …_settings_nav_visible / _nav_badge / _nav_icon / _nav_sublabel, …_settings_description, …_settings_before_form / _after_form, …_settings_main_after, …_settings_sidebar / …_settings_sidebar_{section} (actions), …_icons, …_nav_icons, …_status_cards. Shared by every Siteryn plugin: siteryn_dashboard_plugins and siteryn_deactivation_feedback_endpoint.

Pro

Hook	Use
`…_pro_loaded` · `…_pro_upgrade` · `…_pro_deactivate`	Lifecycle
`…_pro_license_activated` · `…_pro_license_deactivated`	License changes
`…_pro_client_ip`	The visitor IP used for rate limits (set it behind a CDN)
`…_pro_admin_config`	Admin script config
`…_pro_fbt_build` · `…_pro_fbt_weekly` · `…_pro_license_check`	Scheduled jobs

Examples

Never recommend a category

add_filter( 'siteryn_ai_product_recommendations_is_recommendable', function ( $ok, $product ) {
	return $ok && ! has_term( 'gift-cards', 'product_cat', $product->get_id() );
}, 10, 2 );

Boost high-margin products

add_filter( 'siteryn_ai_product_recommendations_rule_score', function ( $score, $product, $context ) {
	return 'yes' === $product->get_meta( '_high_margin' ) ? $score + 3 : $score;
}, 10, 3 );

Move the product page list

add_filter( 'siteryn_ai_product_recommendations_product_page_position', function () {
	return array( 'hook' => 'woocommerce_after_single_product', 'priority' => 5 );
}, 20 ); // above 10 to override Pro's Position setting

Send the brand to the AI

add_filter( 'siteryn_ai_product_recommendations_prompt_payload', function ( $payload, $source ) {
	foreach ( $payload['candidates'] as &$candidate ) {
		$candidate['brand'] = (string) wc_get_product( $candidate['id'] )->get_attribute( 'pa_brand' );
	}
	return $payload;
}, 10, 2 );

Tag add to cart clicks from lists

add_filter( 'siteryn_ai_product_recommendations_card_button_attributes', function ( $attrs, $product, $placement ) {
	$attrs['data-siteryn_source'] = $placement;
	return $attrs;
}, 10, 3 );

Pro: real visitor IP behind Cloudflare

add_filter( 'siteryn_ai_product_recommendations_pro_client_ip', function ( $ip ) {
	return isset( $_SERVER['HTTP_CF_CONNECTING_IP'] )
		? sanitize_text_field( wp_unslash( $_SERVER['HTTP_CF_CONNECTING_IP'] ) )
		: $ip;
} );