wc-customer-and-sessions

WooCommerce customers and sessions

Use this skill whenever code touches the active shopper, account profile, cart-flow state, or Store API session.

The critical distinction

WC()->customer is created in session mode:

new WC_Customer( get_current_user_id(), true );

Its data store is WC_Customer_Data_Store_Session. Calling WC()->customer->save() updates the WooCommerce session for both guests and logged-in users; it does not persist account fields to user meta.

To edit a registered customer's durable profile, load a separate non-session object:

$customer = new WC_Customer( $user_id );
$customer->set_billing_phone( $phone );
$customer->save();

Never use the active session object as a shortcut for an account-profile write.

WC_Customer::get_meta_data() is not a safe way to publish a user's entire metadata bag. WooCommerce filters its own customer model's internal/account-preference keys (WooCommerce 11.0 also excludes WordPress's infinite_scrolling preference), but arbitrary third-party user meta can still be private. REST responses, exports, and headless profiles should use an explicit allowlist of extension-owned keys rather than forwarding customer meta wholesale.

Initialization boundaries

On normal cart and checkout requests WooCommerce initializes WC()->session, WC()->customer, and WC()->cart. They are not guaranteed in early hooks, WP-CLI, cron, arbitrary REST routes, or admin requests.

add_action( 'wp_loaded', static function (): void {
    if ( ! function_exists( 'WC' ) || ! WC()->session ) {
        return;
    }

    $campaign = WC()->session->get( 'myplugin_campaign', '' );
} );

Do not call WC()->initialize_cart() globally just to make a property non-null. Initialize cart/session state only in a request that genuinely needs shopper state.

Store plugin state in the session

add_action( 'wp_loaded', static function (): void {
    if ( ! WC()->session ) {
        return;
    }

    WC()->session->set(
        'myplugin_quote',
        array(
            'product_id' => absint( $_POST['product_id'] ?? 0 ),
            'quantity'   => max( 1, absint( $_POST['quantity'] ?? 1 ) ),
        )
    );

    // Must happen before headers are sent. set() marks data dirty; the DB row
    // is written later by save_data(), normally during shutdown.
    WC()->session->set_customer_session_cookie( true );
} );