cpq-pricing-rules

# CPQ Pricing Rules

Use this skill when configuring the Salesforce CPQ pricing engine: creating Price Rules that fire during quote calculation, building Discount Schedules for volume-based pricing, setting up Block Pricing for fixed-price quantity ranges, configuring Percent of Total products, and establishing Contracted Prices for account-specific rate overrides. This skill does not cover standard Salesforce Pricebook pricing or CPQ product catalog configuration.

---

## Before Starting

Gather this context before working on anything in this domain:

- Confirm the Salesforce CPQ managed package (`SBQQ__`) is installed. All CPQ pricing objects (`SBQQ__PriceRule__c`, `SBQQ__DiscountSchedule__c`, `SBQQ__ContractedPrice__c`, `SBQQ__BlockPrice__c`) require it.
- Understand the full pricing waterfall the business requires. CPQ applies pricing in this order: list price → contracted price → block pricing → discount schedules → price rules. Changes to any layer can be overwritten by a later layer if rules are not ordered correctly.
- Identify whether discounts are per-line, volume-based across the order, or account-specific contracted rates. Each requires a different CPQ mechanism.
- Determine the required execution order of price rules early. Two rules with the same Evaluation Order fire in undefined sequence — this is the most common source of inconsistent pricing bugs.
- Verify whether CPQ's debug logging is available in the org. The CPQ Calculator debug mode logs each pricing step to the browser console, which is essential for diagnosing waterfall issues.

---

## Core Concepts

### CPQ Quote Calculation Engine and the Price Waterfall

When a CPQ quote is saved or manually recalculated, the CPQ calculation engine runs synchronously and applies pricing in a defined sequence known as the price waterfall:

1. **List Price** — The `PricebookEntry.UnitPrice` for the product/pricebook combination.
2. **Contracted Price** — If an active `SBQQ__ContractedPrice__c` record exists for the Account + Product combination, it overrides the list price.
3. **Block Pricing** — If the product has `SBQQ__BlockPrice__c` records, per-unit pricing is replaced with the fixed price for the matching quantity range.
4. **Discount Schedules** — `SBQQ__DiscountSchedule__c` volume or term tiers apply an additional percentage discount.
5. **Price Rules** — `SBQQ__PriceRule__c` records fire in ascending Evaluation Order and can overwrite any field on the quote or quote line, including the net price.

Understanding this sequence is critical: a Price Rule that sets the unit price executes after contracted prices, so a contracted price can still be further modified by a price rule if the rule targets the correct field.

### Price Rules: Conditions, Lookup Queries, and Actions

A Price Rule (`SBQQ__PriceRule__c`) is the core mechanism for conditional pricing logic. Each rule has three parts:

**Price Conditions** (`SBQQ__PriceCondition__c`) define *when* the rule fires. Conditions evaluate fields on the Quote (`SBQQ__Quote__c`), Quote Line (`SBQQ__QuoteLine__c`), or a Lookup table. Supported operators include: equals, not equals, greater than, less than, contains. All conditions on a rule must be true for the rule to fire (AND logic). Multiple rules with OR logic require separate rule records.

**Lookup Queries** (`SBQQ__LookupQuery__c`) are optional. They pull values from a CPQ Lookup Object (`SBQQ__LookupData__c`) — a custom data table useful for pricing matrices (e.g., a tier rate that depends on both product family and contract term). The Lookup Query maps input fields from the quote line to rows in the data table and returns a result field that Price Actions can reference.

**Price Actions** (`SBQQ__PriceAction__c`) define *what* the rule does. Each action sets a target field on the quote or quote line to a value sourced from a static value, a field on the quote/line, or a Lookup result field. Common targets: `SBQQ__SpecialPrice__c` (the adjusted price), `SBQQ__Discount__c`, `SBQQ__AdditionalDiscount__c`.

**Evaluation Order** (`SBQQ__EvaluationOrder__c`) is a numeric field on each Price Rule. Rules fire in ascending numeric order. Rules with the same evaluation order fire in undefined sequence — always assign unique evaluation order values across all active price rules.

### Discount Schedules

A Discount Schedule (`SBQQ__DiscountSchedule__c`) applies tier-based discounts based on quantity or term. Tiers (`SBQQ__DiscountTier__c`) define the lower bound of each range and the discount percentage for that range.

**Volume-based** schedules: the applicable tier is determined by the quantity on the quote line. The entire line receives the tier's discount.

**Term-based** schedules: the applicable tier is determined by the subscription term in months. Used for term-length incentives.

Discount Schedules are attached to a product via `SBQQ__DiscountSchedule__c` on the Product2 record. They apply during the calculation engine run after block pricing.

### Block Pricing

Block Pricing (`SBQQ__BlockPrice__c`) replaces per-unit pricing with a fixed price for a given quantity range. When block pricing is active for a product, the CPQ engine does not multiply the unit price by quantity — instead it returns the fixed block price directly. This is the correct mechanism for software licensing tiers where 1–10 seats cost $500 flat, 11–25 cost $900 flat, etc.

Block Pricing records require: Product (`SBQQ__Product__c`), Pricebook (`SBQQ__Pricebook__c`), lower bound quantity (`SBQQ__LowerBound__c`), upper bound quantity (`SBQQ__UpperBound__c`), and price (`SBQQ__Price__c`).

**Important:** Block Pricing and Discount Schedules can coexist on the same product but will both apply, risking double-discounting. When Block Pricing is in use, Discount Schedules attached to the same product should typically be removed or the price rule should be designed to avoid stacking.

### Percent of Total Pricing

Products with `SBQQ__PricingMethod__c = 'Percent of Total'` are priced as a percentage of other line items on the quote. The `SBQQ__PercentOfTotalBase__c` field controls which lines are included in the base (Regular lines, all lines, or a specific product category). This is the correct mechanism for maintenance or support products priced as a percentage of the software they cover — no price rule is needed.

### Contracted Prices

`SBQQ__ContractedPrice__c` records establish account-specific pricing overrides. Each record links an Account, a Product, and a price (or discount). Contracted Prices are generated automatically when a CPQ contract is activated (from a Won Opportunity with a Subscription product), or they can be created manually.

The CPQ engine checks for a matching Contracted Price record during calculation and applies it before block pricing or discount schedules. A price rule can still modify the resulting price if it fires after the contracted price is applied.

---

## Common Patterns

### Pattern: Volume Discount via Discount Schedule

**When to use:** A product should receive a larger discount as the ordered quantity increases, using pre-defined tier breakpoints.

**How it works:**
1. Create a Discount Schedule record with `SBQQ__Type__c = 'Range'` and `SBQQ__DiscountUnit__c = 'Percent'`.
2. Create Discount Tier records for each quantity breakpoint: e.g., 1–10: 0%, 11–25: 10%, 26–100: 20%.
3. Set `SBQQ__DiscountSchedule__c` on the Product2 record to point to the schedule.
4. Test by adding the product to a CPQ quote at different quantities and confirming the correct tier fires.

**Why not the alternative:** Using a Price Rule to replicate volume tiers with multiple conditions is possible but creates maintenance overhead. Discount Schedules are the correct, first-class mechanism for quantity-based tier pricing and are easier to update without changing rule logic.

### Pattern: Conditional Price Rule with Lookup Matrix

**When to use:** The discount or price depends on a combination of quote attributes — for example, a rate that varies by product family AND contract term, requiring a matrix lookup rather than simple conditions.

**How it works:**
1. Create a CPQ Lookup Object (custom object with `SBQQ__` fields) with columns representing the matrix inputs (e.g., Product Family, Term) and the result (e.g., Discount).
2. Create records in the Lookup Object for each combination in the pricing matrix.
3. Create a Lookup Query that maps Quote Line fields (e.g., `SBQQ__ProductFamily__c`, `SBQQ__SubscriptionTerm__c`) to the lookup input columns.
4. Create a Price Rule with a Price Condition that always evaluates to true (or targets a specific product family), a Lookup Query reference, and a Price Action that sets `SBQQ__Discount__c` from the lookup result field.
5. Assign a unique Evaluation Order. Test with quote lines at multiple term/family combinations.

**Why not the alternative:** Hardcoding matrix values as multiple Price Conditions per rule creates a combinatorial explosion of rules. The Lookup Object pattern externalizes the matrix data, making it maintainable without rule changes.

### Pattern: Account Contracted Pricing

**When to use:** A specific account has negotiated rates that should always override list price for designated products.

**How it works:**
1. For contract-generated contracted prices: ensure CPQ contract activation is configured (`SBQQ__RenewedContract__c` flow, Contracted Price generation enabled in CPQ settings under Contracting).
2. For manual contracted prices: create `SBQQ__ContractedPrice__c` records directly, setting Account, Product, and the contracted price or discount.
3. Verify CPQ settings have "Generate Contracted Prices" enabled under Setup > Installed Packages > CPQ Settings > Contracting.
4. Test by creating a quote for the contracted account and confirming the line price shows the contracted rate, not the list price.

**Why not the alternative:** Using a Price Rule with an Account condition to hardcode account-specific rates creates a maintenance burden as accounts scale. Contracted Price records are the correct mechanism — they are account-data-driven, not rule-logic-driven.

---

## Decision Guidance

| Situation | Recommended Approach | Reason |
|---|---|---|
| Quantity-based tier discounts on a product | Discount Schedule with tiers | First-class CPQ mechanism; easier to maintain than rules |
| Fixed price for a quantity range (not per-unit) | Block Pricing records | Disables per-unit math; correct for seat-tier licensing |
| Support/maintenance product priced as % of software | `SBQQ__PricingMethod__c = 'Percent of Total'` | No rule needed; built-in pricing method |
| Account-specific negotiated rates | Contracted Price records | Account-data-driven; scales without rule proliferation |
| Pricing dependent on multiple quote attributes (matrix) | Price Rule + Lookup Query + Lookup Object | Externalizes matrix data; avoids rule explosion |
| Simple conditional discount (e.g., specific product family) | Price Rule with Price Conditions | Appropriate when logic is simple and stable |
| Multiple price rules that interact | Assign unique Evaluation Order values | Same evaluation order = undefined execution sequence |
| Block Pricing + Discount Schedule on same product | Remove or disable one; or use Price Rule to control | Both apply during waterfall — double-discounting risk |

---

## Recommended Workflow

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

1. **Map the full pricing model before touching configuration.** Document all pricing mechanisms required: which products use discount schedules, block pricing, percent of total, contracted pricing, or price rules. Identify any interactions between mechanisms (e.g., a product that has both block pricing and a price rule). This prevents waterfall ordering surprises.
2. **Configure base pricing mechanisms first.** Set up Discount Schedules, Block Price records, and Percent of Total pricing methods on products before creating Price Rules. These are evaluated earlier in the waterfall and establishing them first makes it easier to test price rule behavior in isolation.
3. **Create Contracted Price records for applicable accounts.** If contracted pricing is required, set up Contracted Price records (manually or via contract activation) before configuring price rules that interact with contracted rates. Test with a quote for a contracted account to confirm the correct base price before rules are applied.
4. **Build Price Rules with unique Evaluation Orders.** For each conditional pricing requirement, create a Price Rule with explicit, unique Evaluation Order values (use increments of 10 to allow future insertion). Create Price Conditions for the when logic, Lookup Queries if matrix data is needed, and Price Actions for the field targets. Do not create rules with the same Evaluation Order.
5. **Test each rule in isolation, then in combination.** Create a test quote and add products that trigger each rule. Verify the correct field is set to the correct value. Then test quotes that trigger multiple rules and confirm the combined result matches the intended waterfall output. Use CPQ Calculator debug logging (available via browser console when CPQ debug mode is enabled) to trace which rules fired and in what order.
6. **Document evaluation order and field targets for every active rule.** Record the purpose, Evaluation Order, Conditions, and Action targets of every Price Rule in a pricing design document. This is the single highest-value maintenance artifact — undocumented evaluation orders are the primary source of pricing regression bugs.

---

## Review Checklist

Run through these before marking work in this area complete:

- [ ] All active Price Rules have unique Evaluation Order values — no two rules share the same order number
- [ ] Each Price Rule has at least one Price Condition and at least one Price Action
- [ ] Price Actions reference valid field API names on the Quote or Quote Line
- [ ] Discount Schedules have at least one Discount Tier with a defined lower bound and discount percentage
- [ ] Block Price records have non-overlapping quantity ranges for each product/pricebook combination
- [ ] Contracted Price records are linked to the correct Account and Product, and CPQ Settings has "Generate Contracted Prices" enabled
- [ ] Percent of Total products have `SBQQ__PricingMethod__c = 'Percent of Total'` and the correct `SBQQ__PercentOfTotalBase__c` value
- [ ] Waterfall has been tested end to end with a real quote in a sandbox covering all rule combinations
- [ ] Evaluation Order and field targets for all Price Rules are documented

---

## Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. **Price Rules with the same Evaluation Order produce unpredictable results** — CPQ does not guarantee execution order between rules sharing the same `SBQQ__EvaluationOrder__c` value. The result changes between quote saves. Always use unique evaluation order values, spaced with gaps (10, 20, 30) to allow future insertions.
2. **Block Pricing disables per-unit math entirely** — When a `SBQQ__BlockPrice__c` record matches the quantity range, CPQ returns the block price as-is, ignoring the unit price. If a Discount Schedule is also attached to the product, the schedule's percentage discount still applies to the block price, causing unintended double-pricing reduction. Remove the Discount Schedule from block-priced products unless stacking is explicitly intended.
3. **Contracted Prices do not cascade to related products** — A `SBQQ__ContractedPrice__c` on a bundle parent does not automatically apply to bundle components. Each component product needs its own Contracted Price record if a contracted rate is required at the component level.
4. **Price Actions targeting the wrong field in the waterfall can be silently overwritten** — If a Price Action sets `SBQQ__ListPrice__c` but a later waterfall step recalculates from that field, the action's effect is lost. The safest target for a rule that should produce a final net price is `SBQQ__SpecialPrice__c`, which sits lower in the waterfall. Review the CPQ price field documentation before choosing a target field.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| Price Rule records | `SBQQ__PriceRule__c` with linked Conditions, Lookup Queries (if used), and Actions |
| Discount Schedule records | `SBQQ__DiscountSchedule__c` with `SBQQ__DiscountTier__c` records attached to products |
| Block Price records | `SBQQ__BlockPrice__c` quantity-range records attached to products |
| Contracted Price records | `SBQQ__ContractedPrice__c` account-specific overrides |
| Pricing design document | Evaluation Order table, field targets, and waterfall diagram for all active rules |
| CPQ pricing configuration checklist | Completed checklist from this skill |

---

## Related Skills

- cpq-product-catalog-setup — Use to configure product bundles and product rules before setting up pricing
- products-and-pricebooks — Use for standard Pricebook and PricebookEntry setup that CPQ builds on top of
- cpq-vs-standard-products-decision — Use during requirements gathering to confirm whether CPQ pricing is the right tool
- quote-to-cash-requirements — Use during requirements gathering to map pricing requirements to CPQ mechanisms