Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

How Shopper Works

How Shopper Works

This section describes how Shopper objects are created during different Storefront workflows:

For a visual description of the Shopper workflow, see Shopper Sequence Diagram.

New, Anonymous Login

For a new user, the process begins with the WebCustomerSessionService method findOrCreateCustomerSession. A new Shopper object is created via the ShopperService createAndSaveShopper method. The CustomerSessionService method createWithShopper is used to attach the new Shopper to the newly created CustomerSession object. The CustomerSession is then saved, and the WebCustomerSessionService method createEmptyCustomerOnCustomerSession is used to create an empty Customer object, which is then attached to the Shopper. The WebCustomerSessionService method attachShoppingCartToNewCustomerSession is used to attach a ShoppingCart to the Shopper. At this stage, the user is set up for Anonymous shopping in Storefront. If the WishList is accessed, a new one is generated and also attached to the Shopper via the findOrCreateWishListByShopper method in WishListService.


An anonymous Customer object is always attached to a Shopper.

Customer Login

In the case of a Customer logging into a Storefront, the following steps occur directly after the Anonymous login scenarios. In CustomerSessionFilter, if an Authenticated Customer object is found, the webCustomerSessionService handleCustomerSignIn is called.

First, the Authenticated Customer (known as Registered in the EP domain) is attached to the Shopper, and the Shopper is saved via the saveRegisteredCustomerOnCustomerSession.

Next, the signInCustomer method employs the CustomerSessionService handleShopperChangeAndUpdate method. The existing Shopper on the CustomerSession is replaced with a new Shopper either loaded or created for the Registered Customer.

Relevant data from the old Shopper is then either invalidated, merged, or copied to the new Shopper via the CustomerSessionShopperUpdateHandlers. These include the MboxSessionDataHandlerForShopperUpdates, PromotionCodeInvalidatorForShopperUpdates, ShoppingCartMergerForShopperUpdates, and WishListMergerForShopperUpdates handlers.

Be aware of how the ShoppingCartMergerForShopperUpdates handler functions:

  • If a Guest Customer is performing a checkout, the ShoppingCart from the Anonymous Customer is copied to the new Shopper.
  • In every other case, the previous Shopper ShoppingCart is merged into the new Shopper ShoppingCart. The newly merged cart is saved and attached to the new Shopper. The taxes, estimations, and promotions are cleared and recomputed on the merged ShoppingCart.
  • Then the new Shopper is saved.