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

---
name: Commerce B2B Store Creation Requirements
description: Critical workflow for creating B2B Commerce stores - understand Store vs Storefront distinction
tags: 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:

```bash
# 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

```bash
# 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:**
```bash
# 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](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_digitalexperiencebundle.htm)
- [DigitalExperienceBundle Site](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_digitalexperiencebundle_site.htm)
- [B2B Commerce Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.b2b_commerce_dev_guide.meta/b2b_commerce_dev_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.**