commerce-pricing-and-promotions

# Commerce Pricing and Promotions

This skill activates when a practitioner needs to configure pricebook assignment, tiered pricing, or promotions (including coupons and cart-level discounts) for a Salesforce B2B or D2C Commerce store. It covers the full pricing resolution stack — from pricebook attachment through discount application at checkout — and explains all silent-failure limits that cause real production bugs.

---

## Before Starting

Gather this context before working on anything in this domain:

- **Store type and Id:** B2B and D2C stores share the same pricing objects but differ in guest-buyer access patterns. Retrieve the `WebStore.Id` first.
- **Pricebook resolution limit:** The price engine evaluates at most 25 pricebooks per API call. Pricebooks ranked beyond 25 are silently excluded — no error is raised. Count assigned pricebooks before adding new ones.
- **Promotions do not self-apply:** Activating a Promotion record does not automatically apply discounts at checkout. The checkout flow must include the `PromotionsCartCalculator` subflow. Confirm this before debugging "promotion not working" reports.
- **API version floor:** `PriceAdjustmentSchedule` (tiered pricing parent) requires API v60.0+. `PriceAdjustmentTier` requires API v47.0+. Verify the org's API version before deploying tiered pricing metadata.

---

## Core Concepts

### 1. Pricebook Attachment via Junction Objects

Commerce stores do not use the standard Sales Cloud `Pricebook2Id` field on Account or Opportunity. Two dedicated junction objects control pricebook visibility:

- **`WebStorePricebook`** — links a `Pricebook2` to a `WebStore`. Maximum **5 pricebooks per store**. This is the platform hard limit; the 6th record raises a validation error.
- **`BuyerGroupPricebook`** — links a `Pricebook2` to a `BuyerGroup`. Maximum **50 pricebooks per BuyerGroup** and **100 BuyerGroups per pricebook**.

During price resolution, the engine collects all pricebooks visible to the buyer (via their BuyerGroup memberships and the store's WebStorePricebook assignments), ranks them by the `Priority` field on the junction record, then evaluates at most **25 pricebooks**. Pricebooks ranked 26th or higher are silently skipped — no error, no log entry.

### 2. Tiered Pricing with PriceAdjustmentSchedule

Tiered pricing (quantity-based price breaks) uses two objects linked to a `PricebookEntry`:

- **`PriceAdjustmentSchedule`** (API v60.0+) — the parent record that defines the adjustment method (`Percent`, `Amount`, or `Price`) and the associated `PricebookEntry`.
- **`PriceAdjustmentTier`** (API v47.0+) — child records on the schedule, each defining a `LowerBound`, optional `UpperBound`, and the adjustment value.

The engine applies the matching tier at add-to-cart time. If no tier matches (e.g., quantity falls outside all defined bounds), the base `PricebookEntry.UnitPrice` is used without adjustment.

### 3. Promotions, Segments, and the Checkout Flow Requirement

A `Promotion` record activates a discount but does nothing by itself. The full promotion execution stack is:

1. **`Promotion`** — defines the discount type, priority, start/end dates, and whether it is automatic or coupon-gated.
2. **`PromotionSegmentSalesStore`** — scopes the promotion to a specific `WebStore`.
3. **`PromotionSegmentBuyerGroup`** — further scopes the promotion to a specific `BuyerGroup` (optional; omit for store-wide promotions).
4. **`PromotionCode`** — links a coupon code string to the promotion (only for coupon-gated promotions).
5. **Checkout flow with `PromotionsCartCalculator` subflow** — at checkout, the platform's evaluate API runs all applicable automatic promotions (up to 50) and all applied manual/coupon promotions (up to 50) ranked by `Priority`. Promotions beyond rank 50 in either category are silently excluded.

Hard cart limits enforced at checkout:
- Maximum **5 coupon codes per cart** — adding a 6th raises a user-visible error.
- Maximum **24 item-level adjustments** per cart.
- Maximum **6 order-level adjustments** per cart.

---

## Common Patterns

### Pattern A: Store-Wide Automatic Promotion

**When to use:** A discount applies to all buyers in the store with no coupon required — e.g., a site-wide 10% off sale.

**How it works:**
1. Create a `Promotion` record with `IsActive = true`, `Priority` set relative to other promotions, and `StartDate`/`EndDate` defined.
2. Create a `PromotionSegmentSalesStore` record linking the promotion to the target `WebStore`.
3. Leave `PromotionSegmentBuyerGroup` absent (store-wide scope).
4. Confirm the checkout flow includes the `PromotionsCartCalculator` subflow — without it, the promotion never fires.
5. Test by adding qualifying products to a cart and completing checkout.

**Why not the alternative:** Simply activating the `Promotion` record and assuming it applies is the most common production bug. The checkout flow integration is non-optional.

### Pattern B: BuyerGroup-Scoped Pricebook with Tiered Pricing

**When to use:** Different buyer tiers (e.g., Distributors vs. Retailers) need different base prices, with further quantity-based discounts layered on top.

**How it works:**
1. Create one `Pricebook2` per buyer tier with appropriate `PricebookEntry` records and `UnitPrice` values.
2. Create a `BuyerGroupPricebook` junction record for each `Pricebook2` → `BuyerGroup` pairing. Set `Priority` to control resolution order within the group (lower number = higher priority).
3. Create a `WebStorePricebook` junction record for each pricebook that should also be discoverable at the store level (keep total under 5).
4. For products with quantity breaks, create a `PriceAdjustmentSchedule` linked to the relevant `PricebookEntry`, then add `PriceAdjustmentTier` child records for each quantity band.
5. Verify tier bounds are contiguous and non-overlapping — gaps cause the base price to apply silently.

**Why not the alternative:** Using a single pricebook for all buyers and applying manual price overrides at order entry bypasses the automated resolution stack and cannot scale across thousands of products or buyer groups.

### Pattern C: Coupon-Gated Promotion

**When to use:** A discount applies only when a buyer enters a valid coupon code at checkout.

**How it works:**
1. Create a `Promotion` record with the discount definition. Set it as manual (not automatic) so it does not fire without a code.
2. Create a `PromotionSegmentSalesStore` junction to scope it to the correct store.
3. Create one or more `PromotionCode` records linked to the promotion, each with a unique `Code` string.
4. Buyers enter the code at checkout. The `PromotionsCartCalculator` subflow validates the code and applies the discount.
5. Enforce the 5-coupon-per-cart limit in UX design — surface a clear error message if a buyer attempts to add a 6th code.

---

## Decision Guidance

| Situation | Recommended Approach | Reason |
|---|---|---|
| All buyers in the store get the same price | One `Pricebook2` attached via `WebStorePricebook` | Simplest resolution path; use `BuyerGroupPricebook` only when differentiation is needed |
| Different buyer groups need different prices | Separate `Pricebook2` per tier, attached via `BuyerGroupPricebook` | The resolution engine picks the highest-priority matching pricebook per buyer |
| Quantity breaks on specific products | `PriceAdjustmentSchedule` + `PriceAdjustmentTier` on `PricebookEntry` | Declarative tiered pricing; no custom Apex required |
| Automatic discount for all buyers | `Promotion` + `PromotionSegmentSalesStore`, no coupon | Simplest promotion scope; still requires the checkout flow subflow |
| Discount only for a specific buyer group | `Promotion` + `PromotionSegmentSalesStore` + `PromotionSegmentBuyerGroup` | Scoping to BuyerGroup prevents the discount from leaking to other segments |
| Discount requires a coupon code | `Promotion` (manual) + `PromotionCode` records | Manual promotions are only evaluated when a buyer supplies the code |
| Store is close to the 5-pricebook limit | Consolidate buyer tiers into fewer `Pricebook2` records | The 5-per-store limit is hard; consolidation or BuyerGroupPricebook is the only path |

---

## Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. **Audit current pricebook assignment.** Query `WebStorePricebook` for the target `WebStore.Id` and count existing records. Confirm the count is under 5 before creating new ones. Query `BuyerGroupPricebook` for each relevant `BuyerGroup` and confirm counts are under 50.
2. **Design the buyer-tier-to-pricebook mapping.** Document which `BuyerGroup` maps to which `Pricebook2` and what `Priority` value each junction record should carry. Confirm total unique pricebooks evaluated per buyer does not exceed 25.
3. **Create or update pricebook junction records.** Insert `WebStorePricebook` records for store-level visibility and `BuyerGroupPricebook` records for segment-level assignment. Set `Priority` fields deliberately — the evaluation order determines which price wins when multiple pricebooks contain the same product.
4. **Configure tiered pricing if required.** Create `PriceAdjustmentSchedule` linked to the target `PricebookEntry`, then add `PriceAdjustmentTier` child records with contiguous quantity bounds. Verify no gaps exist between tier upper and lower bounds.
5. **Set up promotions and scope them correctly.** Create `Promotion` records, then wire `PromotionSegmentSalesStore` (required) and optionally `PromotionSegmentBuyerGroup`. For coupon-gated promotions, create `PromotionCode` records. Confirm `IsActive = true` and date ranges are correct.
6. **Verify the checkout flow includes the Promotions subflow.** Open the active checkout flow in Flow Builder and confirm the `PromotionsCartCalculator` element is present in the cart calculation sequence. Without it, no promotions fire.
7. **Run SOQL validation and end-to-end checkout test.** Execute the validation queries in the template to confirm all junction records are wired correctly. Place a test order as a buyer in the affected `BuyerGroup` and confirm prices and discounts resolve as expected.

---

## Review Checklist

Run through these before marking work in this area complete:

- [ ] `WebStorePricebook` count for the store is 5 or fewer
- [ ] `BuyerGroupPricebook` count per BuyerGroup is 50 or fewer; pricebook has 100 or fewer BuyerGroups
- [ ] Total pricebooks visible to any single buyer does not exceed 25
- [ ] `PriceAdjustmentTier` bounds are contiguous (no gaps, no overlaps) for every tiered product
- [ ] Each active `Promotion` has a `PromotionSegmentSalesStore` record for the correct store
- [ ] Checkout flow contains the `PromotionsCartCalculator` subflow element
- [ ] Cart-level adjustments stay within limits: 24 item-level, 6 order-level, 5 coupon codes
- [ ] Promotions ranked beyond 50 (automatic) or 50 (manual) have been removed or re-prioritized
- [ ] End-to-end checkout test performed as a buyer in each affected BuyerGroup

---

## Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. **Silent pricebook exclusion at rank 26+** — The price engine evaluates at most 25 pricebooks per call. If a buyer belongs to multiple BuyerGroups with many pricebook assignments and the total visible pricebooks exceeds 25, the lowest-priority ones are silently skipped. No error is logged. Buyers may see wrong prices with no obvious cause.
2. **Promotions require the checkout flow subflow** — Activating a `Promotion` record and making it active does not apply any discount. The `PromotionsCartCalculator` must be present in the active checkout flow. Removing or bypassing the flow (e.g., during testing with a custom flow) silently disables all promotions.
3. **5 coupon codes per cart is a hard limit** — Attempting to apply a 6th coupon code raises a user-visible error. Design the UX to surface a clear message before this limit is hit, not after.
4. **Silent promotion exclusion at rank 51+** — The evaluate API processes at most 50 automatic and 50 manual promotions per checkout, ranked by `Priority`. Promotions outside that window are silently ignored. Regularly audit promotion counts and retire expired records.
5. **`Pricebook2Id` on Account does not work for Commerce** — The standard Sales Cloud field `Account.Pricebook2Id` is ignored by the Commerce pricing engine. Pricebook assignment for Commerce buyers must go through `WebStorePricebook` and `BuyerGroupPricebook`.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| `WebStorePricebook` records | Junction records linking each `Pricebook2` to the `WebStore` with a `Priority` value |
| `BuyerGroupPricebook` records | Junction records assigning pricebooks to `BuyerGroup` records for segment-specific pricing |
| `PriceAdjustmentSchedule` records | Parent records enabling tiered pricing on a `PricebookEntry` (requires API v60.0+) |
| `PriceAdjustmentTier` records | Child records defining quantity bounds and adjustment values for tiered pricing |
| `Promotion` + segment junction records | `Promotion`, `PromotionSegmentSalesStore`, `PromotionSegmentBuyerGroup` records defining the discount and its scope |
| `PromotionCode` records | Coupon code strings linked to manual promotions |
| SOQL validation queries | Queries verifying junction record wiring before buyer testing |

---

## Related Skills

- `admin/b2b-commerce-store-setup` — covers `WebStore`, `BuyerGroup`, `EntitlementPolicy`, and catalog access wiring that must be in place before pricing configuration