Wcm Data Model Subscriptions Link

WooCommerce Memberships: data model and Subscriptions link

Use this when an integration needs exact storage names. Prefer Memberships public APIs and objects for writes; use these keys for audits, migrations, import/export mapping, and low-level debugging.

Core storage

Membership statuses

WP post statuses use the wcm- prefix. Object methods usually accept/return unprefixed slugs.

Use wc_memberships_get_user_membership_statuses() for the installed status catalog and wc_memberships()->get_user_memberships_instance()->get_active_access_membership_statuses() for statuses that grant access.

Membership plan meta

These keys are stored on wc_membership_plan posts and exposed by WC_Memberships_Membership_Plan::get_meta_keys().

Use plan methods such as get_access_method(), set_access_method(), get_product_ids(), set_product_ids(), get_access_start_date(), and get_access_end_date() rather than direct meta writes.

User membership meta

These keys are stored on wc_user_membership posts and exposed by WC_Memberships_User_Membership::get_meta_keys().

Use wc_memberships_create_user_membership(), wc_memberships_get_user_membership(), and WC_Memberships_User_Membership methods for writes and lifecycle side effects.

Rule storage

Rules are stored in the wc_memberships_rules option, not as posts. Rule type values:

Common rule fields are id, membership_plan_id, active, rule_type, content_type, content_type_name, object_ids, discount_type, discount_amount, access_type, access_schedule, access_schedule_exclude_trial, and meta_data.

Use wc_memberships()->get_rules_instance()->get_rules(), get_plan_rules(), add_rules(), update_rules(), or delete_rules() instead of editing the option directly.

Memberships to Subscriptions relation

WooCommerce Memberships links to WooCommerce Subscriptions by adding extra meta to the wc_user_membership post. The subscription itself is still a WCS shop_subscription.

Public helpers:

$integration = wc_memberships()->get_integrations_instance()->get_subscriptions_instance();
$subscription = $integration ? $integration->get_subscription_from_membership( $user_membership ) : null;
$memberships = $integration ? $integration->get_memberships_from_subscription( $subscription ) : array();

$is_linked = wc_memberships_is_user_membership_linked_to_subscription( $user_membership );

Do not assume a reverse meta key on the subscription. Reverse lookup queries wc_user_membership posts with _subscription_id = {subscription_id}.

Subscription-linked lifecycle

When Subscriptions is active, Memberships may return WC_Memberships_Integration_Subscriptions_User_Membership for linked memberships.

Important behavior:

• Linking calls WC_Memberships_Integration_Subscriptions_User_Membership::set_subscription_id() and fires wc_memberships_user_membership_linked_to_subscription.
• Unlinking deletes _subscription_id and fires wc_memberships_user_membership_unlinked_from_subscription.
• Subscription trial dates can set membership status to free_trial and write _free_trial_end_date.
• Subscription date/status changes can update linked membership dates/statuses.
• If a plan is granted by subscription products, Memberships checks whether the subscription product grants the plan and may keep access tied to subscription activity.
• Installment plan behavior differs: completion can unlink the subscription while keeping membership access according to the plan rules.

Gifting and Memberships

WooCommerce Subscriptions Gifting changes who receives membership access when the gifted subscription product grants a Memberships plan.

Storage bridge:

• Gifted subscription stores recipient user on subscription meta _recipient_user after recipient account resolution.
• Parent order item stores wcsg_recipient = wcsg_recipient_id_{user_id}.
• Memberships grant filtering uses wcsg_recipient to grant access to recipient users instead of the purchaser for gifted items.
• The membership still stores the linked subscription in _subscription_id.

If an order has the same membership-granting product for several recipients, do not pick the first subscription in the order. Use the WCSG/Memberships integration logic or query recipient subscriptions before assigning _subscription_id.

Safe query patterns

// Memberships for a subscription.
$memberships = get_posts( array(
    'post_type'      => 'wc_user_membership',
    'post_status'    => wc_memberships_get_user_membership_statuses( false ),
    'fields'         => 'ids',
    'posts_per_page' => -1,
    'meta_query'     => array(
        array(
            'key'   => '_subscription_id',
            'value' => $subscription_id,
        ),
    ),
) );

// Prefer API for normal code.
$user_membership = wc_memberships_get_user_membership( $user_id, $plan_id );

Common mistakes

// WRONG: this key is not the plan relation in the installed plugin.
$plan_id = get_post_meta( $membership_id, '_member_plan_id', true );

// RIGHT: use the object or post_parent.
$membership = wc_memberships_get_user_membership( $membership_id );
$plan_id = $membership ? $membership->get_plan_id() : 0;

// WRONG: raw post status write misses Memberships side effects.
wp_update_post( array( 'ID' => $membership_id, 'post_status' => 'wcm-active' ) );

// RIGHT: use object status API with unprefixed status.
$membership->update_status( 'active' );

Cross-references

• Use wcm-membership-hooks for lifecycle hooks and REST/webhook extension points.
• Use wcm-access-discounts for access checks, restrictions, drip timing, and member discounts.
• Use wcs-data-model-switching-gifting for Subscriptions order type, subscription meta, switch data, and gifting data.