Wcm Membership Hooks

WooCommerce Memberships: hook map

Use this when building or reviewing an integration that needs to react to WooCommerce Memberships events. This is a curated decision map, not an exhaustive dump of every hook call in the plugin.

Misconception this skill corrects

"Memberships are just posts/meta, so query wc_user_membership posts and update _member_plan_id or post_status directly."

User memberships are stored as custom posts, but the plugin has object wrappers, status hooks, access rules, order-grant metadata, REST/webhook behavior, profile-field storage, and Subscriptions integration. Prefer public functions and WC_Memberships_User_Membership methods unless the task explicitly requires low-level inspection.

When to use this skill

Trigger when ANY of the following is true:

• The user asks for WooCommerce Memberships actions/filters, lifecycle hooks, status hooks, purchase grant hooks, profile fields, REST API hooks, webhooks, member directory, members area, or Subscriptions-linked memberships.
• Code contains wc_memberships_, WC_Memberships_User_Membership, WC_Memberships_Membership_Plan, wc_user_membership, wcm-active, _member_plan_id, _wc_memberships_access_granted, or woocommerce-memberships.
• You need to decide whether to hook at membership creation, post save, status transition, access grant, profile field save, API response shaping, or frontend members-area rendering.

Workflow

1. Identify the layer first: user membership lifecycle, purchase/free-signup grant, access/restriction, discount, profile fields, REST/webhook, members area, CSV/admin, or Subscriptions integration.
2. Prefer public functions and objects over raw WP_Query, wp_update_post(), or direct post meta writes.
3. For status strings, know the boundary: WP post statuses use wcm- prefix, but object methods and lifecycle hooks commonly use unprefixed statuses such as active, paused, cancelled, expired, free_trial, delayed.
4. Before implementing, inspect the installed plugin line with:

rg -n "hook_name|function_name" wp-content/plugins/woocommerce-memberships/src wp-content/plugins/woocommerce-memberships/templates

Storage facts agents must not guess

Memberships registers two CPTs: wc_membership_plan for plans and wc_user_membership for user memberships. A user membership's plan ID is post_parent, and its member/user ID is post_author; the installed plugin does not use _member_plan_id as the plan relation.

Core plan meta keys are _access_method, _access_length, _access_start_date, _access_end_date, _product_ids, _members_area_sections, and _email_content.

Core user membership meta keys are _start_date, _end_date, _cancelled_date, _paused_date, _paused_intervals, _product_id, _order_id, _previous_owners, _renewal_login_token, and _locked.

Membership rules are stored in the wc_memberships_rules option. Rule type values are content_restriction, product_restriction, and purchasing_discount.

When WooCommerce Subscriptions links a membership, the wc_user_membership post gets _subscription_id; subscription-linked memberships may also use _has_installment_plan and _free_trial_end_date.

Active-detection canon

When gating code that registers something at FluentCRM / WP boot time (FluentCRM trigger / action, WC custom block, JFB action, etc.), use a symbol that exists at FILE LOAD — not one declared inside Memberships's own plugins_loaded:10 callback. The symptom of getting this wrong is non-deterministic: works on some installs, your code disappears on others, depending on plugin activation order.

// RIGHT — declared at file scope in woocommerce-memberships.php:83.
// Available the moment WP includes the plugin file, before any hook fires.
class_exists('WC_Memberships_Loader');

// WRONG — load-order race.
// wc_memberships() is declared inside class-wc-memberships.php which
// Memberships's plugins_loaded:10 callback require_onces from init_plugin().
// If your registration callback runs BEFORE Memberships's, function_exists
// returns false and your code skips registration silently.
function_exists('wc_memberships');

Same rule for WC_Memberships itself (the main class): it's loaded INSIDE init_plugin() so class_exists('WC_Memberships') is also racy. The loader class is the safe top-level checkpoint. At call time (REST endpoints, funnel handlers, AJAX) all classes/functions are loaded — the racy checks only matter at registration time.

Public API first

User membership lifecycle hooks

Purchase and free-signup grants

Profile fields

REST API and webhooks

Members area, directory, CSV, admin

Woo Subscriptions integration

If WooCommerce Subscriptions is active, Memberships may use subscription-aware membership objects and lifecycle rules.

Common mistakes

// WRONG: skips Memberships creation/update hooks and object semantics.
wp_insert_post( array(
    'post_type'   => 'wc_user_membership',
    'post_status' => 'wcm-active',
) );

// RIGHT: let Memberships create/renew/update the user membership.
$membership = wc_memberships_create_user_membership( array(
    'user_id' => $user_id,
    'plan_id' => $plan_id,
) );

// WRONG: status meta/post writes bypass object methods and can miss side effects.
wp_update_post( array( 'ID' => $membership_id, 'post_status' => 'wcm-cancelled' ) );

// RIGHT: use the object API; pass unprefixed status.
$membership = wc_memberships_get_user_membership( $membership_id );
if ( $membership instanceof WC_Memberships_User_Membership ) {
    $membership->update_status( 'cancelled', 'Cancelled by external CRM.' );
}

// WRONG: raw "active" check misses Memberships access semantics and delayed/free-trial cases.
$is_member = 'wcm-active' === get_post_status( $membership_id );

// RIGHT: use public checks for business rules.
if ( wc_memberships_is_user_active_member( $user_id, $plan_id ) ) {
    myplugin_enable_feature( $user_id );
}

// WRONG: function_exists() is a load-order race at registration time.
// wc_memberships() is declared inside Memberships's plugins_loaded:10
// callback. If your registrar runs first (also plugins_loaded:10), this
// returns false and your integration silently doesn't register.
add_action( 'plugins_loaded', function () {
    if ( ! function_exists( 'wc_memberships' ) ) {
        return; // racy — sometimes false even when Memberships is active
    }
    register_my_membership_integration();
}, 11 );

// RIGHT: WC_Memberships_Loader is at file scope — race-free.
add_action( 'plugins_loaded', function () {
    if ( ! class_exists( 'WC_Memberships_Loader' ) ) {
        return;
    }
    register_my_membership_integration();
}, 11 );

// WRONG: hardcoding the status list — Memberships allows 3rd parties to add
// their own statuses via the wc_memberships_user_membership_statuses filter.
$statuses = array( 'active', 'paused', 'cancelled', 'expired' );

// RIGHT: read from the registry (UNPREFIXED keys for object methods).
$statuses = wc_memberships_get_user_membership_statuses( true, false );
foreach ( $statuses as $key => $data ) {
    // $key = 'active', 'paused', ...; $data['label'] = 'Active', 'Paused', ...
}

Cross-references

• Use wcm-data-model-subscriptions-link for exact CPT names, meta keys, rule storage, profile-field storage, and Memberships-Subscriptions relation details.
• Use wcm-access-discounts for access checks, restriction/drip hooks, member discounts, and price-adjustment recursion safety.
• Use wcs-subscription-hooks or wcs-renewal-scheduler when the membership is tied to WooCommerce Subscriptions renewal/payment flow.