Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 28 ยท Platform APIs and Data

Customers, Sessions and Profiles

Learn how Salesforce Commerce Cloud models guests and registered customers, session and request scope, profiles, custom attributes, address books, wishlists and privacy.

Every visitor to a Commerce Cloud storefront is a customer, even before they sign in. That surprises people at first, but it makes the code simple: customer always exists, so a basket, a wishlist or a price book assignment can always be attached to someone. What changes between a guest and a registered shopper is whether the customer has a profile, whether they are authenticated, and what data survives the end of the session.

This lesson explains the difference between registered, authenticated and anonymous customers, the scopes in which you can store data (request, session, privacy and profile), how profiles, address books and wishlists work, how external sign-in fits in, and how to keep personal data under control. The real code is read-only, because the site cannot run a Commerce Cloud instance. Two JavaScript stand-ins model session scoping and the customer states, each saying what is real and what is simplified. The Script API basics, including transactions, are in The Script API and Common Classes.

Anonymous, registered and authenticated

A request has a global customer object (in SFRA, req.currentCustomer wraps it). Two flags matter:

  • customer.registered is true when the customer has an account (a profile and credentials).
  • customer.authenticated is true when this session has proved who the customer is, normally by signing in.

They are not the same. Three states exist:

  • Anonymous: no account, customer.profile is null. This is a guest. Guests can fill a basket and check out without registering.
  • Authenticated: signed in. Account pages, saved addresses and order history are available.
  • Registered but not authenticated: the platform recognizes an account, usually through a "remember me" cookie after the session has expired, but the shopper has not proved their identity in this session. They can browse as themselves (for example see a personalised greeting), but sensitive actions should demand a new login.
stateDiagram-v2
    [*] --> Anonymous
    Anonymous --> Authenticated: login or registration
    Authenticated --> Anonymous: logout
    Authenticated --> Registered_not_authenticated: session ends, remember-me cookie kept
    Registered_not_authenticated --> Authenticated: password entered again

A customer moves between three states; routes that expose personal data should check authenticated, not only registered.

SFRA enforces this with middleware such as userLoggedIn.validateLoggedIn (it checks req.currentCustomer.profile and authentication) in front of account routes. Never base access to private data on the existence of a profile alone.

Registering and signing in

The CustomerMgr class is the entry point:

JavaScript
var CustomerMgr = require('dw/customer/CustomerMgr');
var Transaction = require('dw/system/Transaction');

// Register
Transaction.wrap(function () {
    var newCustomer = CustomerMgr.createCustomer('[email protected]', 'a-strong-passphrase');
    var profile = newCustomer.profile;
    profile.firstName = 'Ana';
    profile.lastName = 'Lopez';
    profile.email = '[email protected]';
});

// Sign in: authenticate first, then log in the result
var status = CustomerMgr.authenticateCustomer('[email protected]', password);
if (status.authenticated) {
    CustomerMgr.loginCustomer(status, rememberMe);
}

// Sign out
CustomerMgr.logoutCustomer(false);   // true would keep the "remember me" recognition

The login name and the password are stored in the customer's credentials; the platform stores passwords hashed, and you never read or store them yourself. Rate limiting, lockout after failed attempts and password rules are platform and site settings plus your own controller logic, covered in Security, Sessions and Compliance. Notice that registration writes data, so it runs in a transaction. When a guest signs in, the guest basket is carried over to the account, so a shopper who filled a cart and then logged in does not lose it.

Where to keep data: the four scopes

You will often need to remember something: a selected store, a referral code, a consent decision, a loyalty tier. The platform offers scopes with different lifetimes.

Scope Where Lives until Typical use
Page pageContext in templates End of the template render Values shared between includes
Request request.custom End of the request Passing data between hooks, middleware and templates
Session session.custom The session ends Browsing choices, a selected store, an A/B group
Privacy session.privacy Session end or logout Data that belongs to a person and must not leak to the next one
Profile customer.profile.custom Deleted by you Data that must survive across sessions, for registered customers only

The key distinction is session versus privacy. After a shopper logs out, the next person on a shared computer starts with a fresh identity, and anything you stored in session.custom could still be there. Data that identifies a person or reveals their choices belongs in session.privacy, which is cleared on logout. In SFRA, req.session.privacyCache.set(key, value) and .get(key) wrap session.privacy. Keep session values small and simple (strings, numbers, booleans); a session is stored and loaded on every request, so storing a large object makes every page slower.

The first TryIt models these scopes. Each call to startRequest() creates fresh request storage, while the session persists. What is real: the lifetimes in the table above, and privacy data disappearing on logout. What is simplified: the platform creates a new session identifier at login and has more storage rules, and pageContext is omitted.

JS Request, session, privacy and profile scope (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

After logout, session.custom.store is still there, session.privacy.email is gone, and the profile value comes back only when Ana signs in again. That is the behavior to design around: put the email in the privacy scope, and a shared kiosk does not show the previous person's address to the next one.

Profiles, custom attributes and the address book

A profile (customer.profile) holds personal data: names, email, phone, birthday, gender, and a custom object for your own attributes. Custom attributes are defined in the data model of the system object type Profile (see Custom Objects and System Object Extensions), and then written inside a transaction:

JavaScript
Transaction.wrap(function () {
    customer.profile.custom.newsletterOptIn = true;
    customer.profile.custom.preferredStore = 'berlin-1';
});

Read them defensively, since a custom attribute may be null for older customers: customer.profile.custom.newsletterOptIn === true.

The address book (customer.addressBook) stores named addresses. Each address has an ID chosen by you (the shopper's label or a generated ID) and a preferred flag:

JavaScript
Transaction.wrap(function () {
    var book = customer.addressBook;
    var address = book.createAddress('home');
    address.firstName = 'Ana';
    address.address1 = '12 Linden Street';
    address.city = 'Berlin';
    address.postalCode = '10115';
    address.countryCode = 'DE';
    book.setPreferredAddress(address);
});

The platform provides product lists for wishlists and gift registries through ProductListMgr. A wishlist belongs to a customer, holds list items that point to products and can be public or private:

JavaScript
var ProductListMgr = require('dw/customer/ProductListMgr');
var ProductList = require('dw/customer/ProductList');

Transaction.wrap(function () {
    var list = ProductListMgr.createProductList(customer, ProductList.TYPE_WISH_LIST);
    list.createProductItem(product);
});

Wishlist pages need the shopper's identity, so they are personalized and must not be cached for everyone; the account state belongs in the small per-user calls that your storefront makes, in line with Caching and Performance.

Customer groups and external sign-in

Customers are members of customer groups: system groups such as "Everyone", "Registered" and "Unregistered", plus groups you define by rules (for example by a profile attribute or an external segment). Groups can drive price book assignments, promotions and content visibility. In code: customer.isMemberOfCustomerGroup('VIP').

Shoppers can also sign in through an external provider such as Google, Apple or a corporate identity system. The classic SFRA storefront supports OAuth2 providers configured in Business Manager; after the provider confirms the identity, the platform links it to a customer through an external profile (customer.externalProfiles) and logs them in. Headless storefronts use the Shopper Login and API Access Service (SLAS) instead, introduced in OCAPI and SCAPI. In both cases, never trust an email address from a provider without confirming that the provider verified it, or an attacker can claim someone else's account.

The second stand-in: access by customer state

The second TryIt expresses the three customer states and what each may do. The rule is simple and easy to forget: protect private data with authenticated.

JS What each customer state may access (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Privacy and good habits

  • Collect less. Every attribute you add to a profile becomes data you must protect, export on request and delete on request. Prefer references (a customer number in your CRM) over copies.
  • Keep personal data out of logs, URLs and custom objects that many people can read, and out of cached HTML. A page with a name in it cannot be cached for everyone.
  • Respect consent. SFRA has consentTracking middleware and a tracking-consent flow; analytics and marketing scripts must not run before the shopper agrees where the law requires it.
  • Deleting an account removes the customer and profile (CustomerMgr.removeCustomer), but orders are separate records with their own retention rules. Decide, with your legal contacts, what an erasure request must remove, and write that down as a procedure.
  • Hash, do not store, secrets. Passwords stay in the credentials object. Do not copy them into custom attributes, logs or session values.
  • Use the right scope. Anything you would not want the next person at a shared computer to see goes into session.privacy.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A shopper returns after the session expired. The "remember me" cookie identifies the account, but they have not entered a password. Which flags describe the customer?

    The platform recognizes the account (registered), but identity has not been proven in this session (not authenticated). Private pages should require a login in this state.
  2. 2. Where should you store a shopper's email address temporarily so it disappears at logout?

    session.privacy is cleared when the shopper logs out, while session.custom survives logout. A global variable would be shared between all shoppers and must never hold shopper data.
  3. 3. What must you do to write profile.custom.newsletterOptIn = true?

    Profile data is persistent, so all writes need a transaction. The custom attribute must also exist in the Profile object's metadata.
  4. 4. Why can't a wishlist page be cached publicly and shared between shoppers?

    A shared cache returns the same HTML to everyone. Personal pages must not be cached that way, and personalised parts should be fetched separately.
  5. 5. What does a guest checkout rely on, since a guest has no account?

    Every visitor has a customer object. Anonymous customers have no profile, but they have a session and a basket, which is enough for checkout.

Summary

  • Every visitor is a customer: anonymous (no profile), authenticated, or registered but not authenticated. Protect private data with authenticated.
  • CustomerMgr registers, authenticates, logs in and out; writes happen in transactions.
  • Choose the right scope: request.custom, session.custom, session.privacy (cleared at logout) or profile.custom (persistent).
  • Profiles, address books and product lists (wishlists) belong to registered customers; customer groups drive pricing, promotions and content.
  • External sign-in links an identity from a provider to a customer through an external profile; headless storefronts use SLAS.
  • Minimize personal data, keep it out of cached pages and logs, and define erasure procedures.

Next: Custom Objects and System Object Extensions