afv-library/rules/commerce/commerce-b2b-store-requirements.md

name	description	tags
Commerce B2B Store Creation Requirements	Critical workflow for creating B2B Commerce stores - understand Store vs Storefront distinction	commerce, b2b, scom, scom b2b, commerce b2b, store, storefront, lwr, experience-cloud, rules

⚠️ CRITICAL: Commerce Store vs Storefront Distinction

When creating a Commerce B2B solution, you must understand the distinction between two separate but related components:

1. Commerce Store (For Merchandisers)

What it is:

• Runtime data and configuration created in the Salesforce org
• NOT source-controllable metadata
• Created through the Commerce app UI or Commerce APIs

What it includes:

• Store configuration and settings
• Default buyer groups
• Entitlement policies
• Pricing policies
• Payment, tax, and shipping configurations
• Product catalog associations
• Price book mappings
• Inventory locations
• Search index configurations

Where it lives:

• Data records in standard Commerce objects (WebStore, BuyerGroup, EntitlementPolicy, etc.)
• Configured via Setup → Commerce → Stores

2. Storefront (For Buyers)

What it is:

• Digital Experience (LWR site) for buyer-facing shopping experience
• Source-controllable as ExperienceBundle metadata
• Created automatically when you create a Commerce Store, or manually via Experience Builder

What it includes:

• ExperienceBundle metadata (StorefrontName.digitalExperience-meta.xml, routes, views, navigation)
• Lightning Web Components (product list, product detail, cart, checkout)
• Branding and theme configuration
• Page layouts and content
• Custom LWCs for unique functionality

Where it lives:

• force-app/main/default/digitalExperiences/site/StorefrontName/
• Example: force-app/main/default/digitalExperiences/site/My_B2B_Store1/
• Retrievable and deployable via Salesforce CLI

---

🚫 Common Mistake: Creating Storefront Metadata from Scratch

DO NOT attempt to manually create Commerce storefront metadata files (StorefrontName.digitalExperience-meta.xml) from scratch in your repository.

Why this fails:

• Commerce storefronts have complex dependencies on the Commerce Store data
• Out-of-box Commerce components require specific configurations tied to WebStore records
• Commerce-managed components (search, PLP, PDP, cart, checkout) are generated and configured by the Commerce setup wizard
• Missing the Store-to-Storefront associations will result in non-functional pages

---

Agent Guidance: Interactive Flow Requirements

When user asks to create Commerce storefront, agent MUST:

1. Follow the interactive flow from prompts/commerce/create-retrieve-b2b-storefront.md
2. Explain the Store vs Storefront concept first
3. Guide user to create B2B Store in org with clear steps
4. Get explicit confirmation that Store was created
5. Run sf org list metadata --metadata-type DigitalExperienceConfig to list available sites
6. Let user select from the list (don't assume store name)
7. Retrieve with: sf project retrieve start -m DigitalExperienceBundle:site/<store-name>
8. Provide next steps with documentation links

What agents should NEVER do:

• Create .digitalExperience-meta.xml files from scratch
• Skip the Store creation step
• Assume store name without listing/confirming
• Deploy without verifying Store exists in target org

---

✅ Required Workflow for Creating Commerce B2B Sites

Step 1: Create Commerce Store in the Org (MUST BE DONE FIRST)

1. Access Commerce Setup:

   • Navigate to Setup → Commerce → Stores
   • OR use the Commerce app from App Launcher → Create / Select App

2. Create New Store (via UI):

   • Click "Create Store" or "Setup New Store"
   • Choose store type: B2B Store - For business buyers with account hierarchies, buyer groups, negotiated pricing
   • Follow the store setup wizard

3. Store Setup Wizard will create:

   • WebStore record with unique name
   • Default buyer group (associated with Accounts)
   • Default entitlement policies (who can see which products)
   • Default price book association
   • Default checkout flow configuration
   • Associated Digital Experience (Storefront) - This is auto-generated!

4. Configure Store Settings:

   • Payment gateway (Stripe, Adyen, etc.)
   • Tax provider (Avalara, Vertex, manual)
   • Shipping methods
   • Search settings
   • Account-based features

5. Verify Store Creation:

   • Setup → All Sites → Find your new Experience Cloud site
   • The site name will match your store name (e.g., "My B2B Store" → "My_B2B_Store")
   • The Experience was created automatically during Store setup

Step 2: Retrieve Digital Experience Metadata (Storefront)

After the Commerce Store is created in the org, retrieve the generated Experience metadata:

# List all Digital Experiences in your org
sf org list metadata --metadata-type DigitalExperienceConfig

# Retrieve the complete ExperienceBundle
# Note: Salesforce appends a number suffix (e.g., "My B2B Store" becomes "My_B2B_Store1")
sf project retrieve start -m DigitalExperienceBundle:site/My_B2B_Store1

What you'll get:

force-app/main/default/digitalExperiences/site/StorefrontName/
├── StorefrontName.digitalExperience-meta.xml  # Digital Experience Bundle metadata
├── sfdc_cms__appPage/                 # App page configuration
├── sfdc_cms__brandingSet/             # Branding assets
├── sfdc_cms__label/                   # Labels and translations
├── sfdc_cms__languageSettings/        # Language configuration
├── sfdc_cms__lwc/                     # Lightning Web Components (custom)
├── sfdc_cms__mobilePublisherConfig/   # Mobile configuration
├── sfdc_cms__route/                   # URL routing configuration
├── sfdc_cms__site/                    # Site settings
├── sfdc_cms__styles/                  # CSS styles
├── sfdc_cms__theme/                   # Theme configuration
├── sfdc_cms__themeLayout/             # Theme layouts
└── sfdc_cms__view/                    # Page definitions (views)
    ├── home/                          # Homepage
    ├── current_cart/                  # Shopping cart page
    ├── current_checkout/              # Checkout page
    ├── detail_*/                      # Product Detail Pages (PDP)
    ├── list_*/                        # Product List Pages (PLP)
    ├── order/                         # Order confirmation
    ├── global_search/                 # Search results
    └── [other pages...]

Example: For a store named "My B2B Store", the folder structure would be:

force-app/main/default/digitalExperiences/site/My_B2B_Store1/
├── My_B2B_Store1.digitalExperience-meta.xml
└── [subdirectories as shown above]

Step 3: Customize Storefront (Optional)

Once you have the retrieved metadata, you can:

1. Add custom LWCs following LDS-first patterns
2. Modify page layouts in Experience Builder
3. Customize branding (colors, fonts, logos)
4. Add content pages (About Us, FAQ, Terms)
5. Configure navigation and menus

Important:

• Test changes in Experience Builder before committing to source control
• Use sf project retrieve start after each change to sync metadata
• Deploy to other orgs using sf project deploy start

Step 4: Version Control Workflow

# After creating store and retrieving metadata
git add force-app/main/default/digitalExperiences/
git commit -m "feat: add My B2B Store digital experience metadata"

# Deploy to scratch org or sandbox (replace My_B2B_Store1 with your storefront name)
sf project deploy start --source-dir force-app/main/default/digitalExperiences/site/My_B2B_Store1

# Note: Commerce Store data must be recreated in target org first!

---

🎯 Summary: The Correct Order

1. ✅ Create Commerce Store in org (Setup → Commerce)
   ↓
2. ✅ Store wizard creates WebStore + Digital Experience
   ↓
3. ✅ Retrieve Experience metadata to local repo
   ↓
4. ✅ Customize and extend (LWCs, pages, branding)
   ↓
5. ✅ Commit to source control
   ↓
6. ✅ Deploy to other orgs (after creating Store in target org)

---

🚨 What NOT to Do

❌ Don't create storefront metadata from scratch

• The Commerce setup wizard generates hundreds of configuration values
• Manual creation will miss critical Store-to-Experience associations

❌ Don't try to deploy storefront without Store

• Deploying Experience metadata to an org without the Commerce Store will fail
• Commerce components require WebStore records to exist

❌ Don't version control Commerce Store data

• WebStore records, BuyerGroups, EntitlementPolicies are runtime data
• Cannot be captured as deployable metadata (use data export/import instead)

❌ Don't skip the Commerce setup wizard

• Even if you think you can do it faster manually
• The wizard creates essential relationships and default configurations

---

📋 Pre-Deployment Checklist for Other Orgs

When deploying your storefront to a new org:

• Target org has Commerce licenses (B2B Commerce)
• Experience Cloud is enabled and domain configured
• Commerce Store has been created in target org (via Commerce app UI)
• WebStore name matches the Experience name in your metadata
• Buyer users and Commerce Admin permissions are assigned
• Product catalog, price books, and inventory exist in target org
• Payment, tax, shipping providers configured
• Only then deploy the Experience metadata: bash sf project deploy start --source-dir force-app/main/default/digitalExperiences/

---

🔗 Related Workflows

For B2B Commerce:

• Create Buyer Accounts and Contacts
• Assign Accounts to Buyer Groups
• Configure negotiated pricing and entitlement policies
• Set up account hierarchies

General Setup:

• Seed product catalog (Products, ProductCategory, ProductCatalog)
• Create price books and price book entries
• Configure inventory (ProductItem, LocationInventory)
• Set up search facets and filters

---

💡 Agent Guidance: What to Create vs What to Retrieve

When user asks: "Create a B2B Commerce storefront"

Your response should be:

1. ✅ Explain the Store vs Storefront distinction
2. ✅ Instruct them to create the Commerce Store in their org first
3. ✅ Provide the Salesforce CLI retrieve commands
4. ✅ Optionally: Create custom LWCs for extending the retrieved storefront
5. ❌ DO NOT create StorefrontName.digitalExperience-meta.xml from scratch

Acceptable to create from scratch:

• Custom LWCs for storefront extensions (hero banners, promotions, custom product cards)
• Content pages that don't use Commerce components
• Utility components (navigation helpers, breadcrumbs)

Must be retrieved from org:

• Core storefront Experience metadata
• Commerce-managed pages (PLP, PDP, Cart, Checkout)
• Store configuration and routing

---

📚 Additional Resources

Commerce Store Setup:

• Setup → Commerce → Stores
• Commerce app from App Launcher → Create / Select App
• Help Article: "Set Up a B2B Commerce Store"

Storefront Customization:

• Experience Builder → Open your store site
• Help Article: "Customize Your Commerce Storefront"
• Developer Guide: "Build Custom Commerce Components"

Metadata Retrieval:

# List all retrievable metadata types
sf org list metadata --metadata-type DigitalExperienceConfig

# Retrieve specific experience
sf project retrieve start -m DigitalExperienceBundle:site/YourStoreName

Documentation:

• DigitalExperienceBundle Metadata
• DigitalExperienceBundle Site
• B2B Commerce Developer Guide

---

🎓 Key Takeaway

Commerce is a TWO-STEP process:

1. Create Store (in org, runtime data) → Generates default storefront
2. Retrieve & Customize Storefront (source control, metadata) → Extend with custom features

Never skip step 1. Never manually create what step 1 generates.