cpq-quote-templates

# CPQ Quote Templates

Use this skill when a practitioner needs to design, configure, or troubleshoot Salesforce CPQ (SBQQ) quote templates: building the section and content hierarchy, defining which quote line fields appear in the line items table, controlling conditional section visibility, producing branded PDF output, or supporting multiple languages. This skill does NOT cover standard Salesforce quote templates configured in Setup > Quote Templates — those use `QuoteLineItem` and are covered by the `admin/quotes-and-quote-templates` skill.

---

## Before Starting

Gather this context before working on anything in this domain:

- **CPQ managed package must be installed**: All CPQ template objects (`SBQQ__QuoteTemplate__c`, `SBQQ__TemplateSection__c`, `SBQQ__TemplateContent__c`, `SBQQ__LineColumn__c`) exist only when the SBQQ managed package is installed. Confirm the package is present before any configuration.
- **Standard quote templates do not work for CPQ**: The most common mistake is directing practitioners to Setup > Quote Templates. Standard templates query `QuoteLineItem`; CPQ lines live in `SBQQ__QuoteLine__c`. The result is a PDF with an empty line items table every time.
- **HTML in CPQ templates is converted to XSL-FO**: CPQ's PDF engine converts HTML content to XSL-FO before rendering. CSS class-based styling, flexbox, CSS grid, and many positioning properties are silently ignored. All styling must use inline styles on every element.
- **Image size limit is 5 MB per image**: Images embedded in template HTML or stored as Salesforce Files referenced in templates must be under 5 MB. Larger images cause PDF generation to fail silently or time out.
- **Multi-language requires separate templates per locale**: CPQ has no native translation layer for quote templates. Each language requires a separate `SBQQ__QuoteTemplate__c` record. Template selection logic must be implemented in a Flow or Process Builder that sets the template lookup field on the quote based on the quote's locale or account language.

---

## Core Concepts

### Template Object Hierarchy

CPQ quote templates are structured across three related objects:

```
SBQQ__QuoteTemplate__c  (the top-level template record)
  └── SBQQ__TemplateSection__c  (ordered sections: Header, Cover Page, Body, Footer)
        └── SBQQ__TemplateContent__c  (content blocks within each section)
```

**SBQQ__QuoteTemplate__c** is the entry point. A quote record has a lookup to a template; when a user clicks "Preview" or generates the document, CPQ walks this hierarchy to build the PDF.

**SBQQ__TemplateSection__c** defines a printable region. Each section has a `SBQQ__Type__c` field that controls its role:

| Section type | Role |
|---|---|
| Header | Appears at the top of every page |
| Cover Page | Full first-page section, printed before body content |
| Body | The main content area; Body sections marked as "Line Items" repeat for each group of quote lines |
| Footer | Appears at the bottom of every page |

Sections have an `SBQQ__Orientation__c` field (Portrait / Landscape) and an `SBQQ__PageBreakBefore__c` checkbox to force page breaks between sections.

**SBQQ__TemplateContent__c** is the leaf node. Each content record belongs to one section and has a `SBQQ__Type__c` that determines what it renders:

| Content type | What it renders |
|---|---|
| HTML | Rich-text / custom HTML rendered inline; supports company logo, custom messaging, fields merged using `{!Quote.FieldName}` merge syntax |
| Line Items | Renders a table of `SBQQ__QuoteLine__c` records; column definitions come from `SBQQ__LineColumn__c` records |
| Quote Terms | Renders the master Terms and Conditions text stored on the template |
| Custom | References a Visualforce page by name; the page must use `renderAs="pdf"` and accept the quote ID as a parameter |

### Line Columns (SBQQ__LineColumn__c)

Line columns define which fields from `SBQQ__QuoteLine__c` appear in the Line Items content type table. Each `SBQQ__LineColumn__c` record specifies:

- `SBQQ__FieldName__c` — the API name of the field on `SBQQ__QuoteLine__c` (standard, custom, or formula)
- `SBQQ__Heading__c` — the column header text printed in the PDF
- `SBQQ__DisplayWidth__c` — percentage of the table width this column occupies (all columns should sum to 100)
- `SBQQ__Alignment__c` — Left, Center, Right
- `SBQQ__FormatType__c` — controls number/currency/percent formatting

Custom fields added to `SBQQ__QuoteLine__c` are fully supported. Formula fields that reference parent `SBQQ__Quote__c` fields are also supported, but complex multi-hop formulas can slow PDF rendering.

### Conditional Visibility

Each `SBQQ__TemplateSection__c` has a `SBQQ__ConditionalPrintField__c` field that accepts the API name of a field on `SBQQ__Quote__c`. The section is shown only when that field evaluates to "truthy" by these exact rules:

| Field type | Condition to show the section |
|---|---|
| Checkbox | Field value = `true` |
| Text | Field value = the exact string `"true"` (case-sensitive) |
| Number / Currency / Percent | Field value != `0` and is not null |

If `SBQQ__ConditionalPrintField__c` is blank, the section always prints. This mechanism is declarative-only — no Apex or formula is evaluated at PDF time beyond the single field lookup.

---

## Common Patterns

### Pattern 1: Branded Cover Page with Company Logo

**When to use:** The org requires a professional first page with the company logo, rep name, account name, and quote expiry date before the line items table.

**How it works:**
1. Create a `SBQQ__TemplateSection__c` with `SBQQ__Type__c = Cover Page` and `SBQQ__PageBreakBefore__c = false`.
2. Create a `SBQQ__TemplateContent__c` child with `SBQQ__Type__c = HTML`.
3. In the HTML content block, reference the logo as a base64-encoded inline `<img>` tag or as a Salesforce Files URL. Keep the file under 5 MB.
4. Use CPQ merge fields (`{!Quote.SBQQ__Account__r.Name}`, `{!Quote.SBQQ__ExpirationDate__c}`) directly in the HTML body.
5. Use only inline CSS (`style="..."`) — no `<style>` blocks and no CSS classes.
6. Click "Preview" on the template to generate a sample PDF before saving the final version.

**Why not a standard Header section:** Headers repeat on every page. A Cover Page section prints once, giving full control over page layout for the introduction.

### Pattern 2: Conditional Discount Summary Section

**When to use:** Show a dedicated "Volume Discount Summary" section only when the quote contains a discount above a threshold — for example, when a custom checkbox field `Show_Discount_Summary__c` is checked by a pricing rule.

**How it works:**
1. Add a custom checkbox field `Show_Discount_Summary__c` to `SBQQ__Quote__c`.
2. Create a CPQ Price Rule or Flow that sets this checkbox to `true` when any line's discount exceeds the threshold.
3. Create a Body `SBQQ__TemplateSection__c` for the discount summary.
4. Set `SBQQ__ConditionalPrintField__c = Show_Discount_Summary__c` on the section.
5. Add an HTML content block inside the section with the discount summary layout.

**Why not use HTML visibility tricks:** CSS `display:none` and `visibility:hidden` are not reliably honored by the XSL-FO renderer. The server-side conditional field is the only reliable mechanism.

### Pattern 3: Multi-Language Templates via Flow

**When to use:** The org sells in multiple countries and needs quote PDFs in the customer's language.

**How it works:**
1. Create one `SBQQ__QuoteTemplate__c` per language with all content authored in that language.
2. Add a custom picklist `Quote_Language__c` to `SBQQ__Quote__c` (or read from `Account.BillingCountry` / `Contact.Language__c`).
3. Build a Record-Triggered Flow on `SBQQ__Quote__c` that fires on create/update of the language field.
4. Use Decision elements to branch by language and use Assignment elements to set `SBQQ__Quote__c.SBQQ__Template__c` to the correct template record ID.
5. Users can still manually override the template on the quote if needed.

**Why not translate within one template:** CPQ's template engine has no translation table. All text in HTML and Quote Terms content blocks is static.

---

## Decision Guidance

| Situation | Recommended Approach | Reason |
|---|---|---|
| Org has CPQ (SBQQ) installed, needs branded PDF | Use `SBQQ__QuoteTemplate__c` hierarchy | Standard Setup > Quote Templates will produce empty line items |
| Need to show/hide a section based on quote data | Use `SBQQ__ConditionalPrintField__c` on the section | CSS visibility is not reliable in XSL-FO rendering |
| Need complex Apex-driven layout or dynamic tables | Use Custom content type pointing to a Visualforce page | Only option for Apex-driven content; HTML content type cannot call Apex |
| Need to include custom `SBQQ__QuoteLine__c` fields in table | Add `SBQQ__LineColumn__c` records to the Line Items content | Standard configuration; no code required |
| Need to support 3 languages | Create 3 separate `SBQQ__QuoteTemplate__c` records, use Flow to assign | No native translation layer in CPQ templates |
| Image is over 5 MB | Resize/compress before uploading, or use an external CDN URL | 5 MB per-image limit; exceeding it silently breaks PDF |
| Need page breaks between sections | Set `SBQQ__PageBreakBefore__c = true` on the section | Declarative; no custom code needed |

---

## Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on CPQ quote template design:

1. **Verify CPQ installation and existing templates**: Confirm `SBQQ__QuoteTemplate__c` is accessible in the org. Run a SOQL query or check Setup > Installed Packages for the Salesforce CPQ managed package. List any existing templates to avoid duplicating work.
2. **Define the section structure**: Map out which sections the PDF needs — Cover Page, Header, one or more Body sections (line items, pricing notes, discount summary), Footer. Decide which sections are conditional and identify the controlling field on `SBQQ__Quote__c` for each.
3. **Create the template and section records**: Create the `SBQQ__QuoteTemplate__c` record, then create ordered `SBQQ__TemplateSection__c` children with correct `SBQQ__Type__c`, `SBQQ__DisplayOrder__c`, and `SBQQ__ConditionalPrintField__c` values.
4. **Author content blocks**: For each section, create `SBQQ__TemplateContent__c` records. For HTML blocks, write all styles inline and test merge field syntax using `{!Quote.FieldAPIName}`. For Line Items blocks, create `SBQQ__LineColumn__c` records pointing to the required `SBQQ__QuoteLine__c` fields; verify column width percentages sum to 100.
5. **Preview against a real quote**: Open an existing CPQ quote in the org, set the `SBQQ__Template__c` lookup to the new template, and click "Preview" to generate a sample PDF. Check that all sections render, line items are populated, and conditional sections appear or hide correctly.
6. **Fix CSS and image issues**: If sections appear garbled, inspect the HTML and replace any class-based or block-level CSS with inline styles. If images are missing, verify file size is under 5 MB and the image URL is publicly accessible or base64-encoded.
7. **Set up template assignment logic**: If the org needs multi-language support or automated template selection, build the Record-Triggered Flow that sets `SBQQ__Quote__c.SBQQ__Template__c` based on the relevant criteria. Test by changing the controlling field and regenerating the PDF.

---

## Review Checklist

Run through these before marking work in this area complete:

- [ ] CPQ managed package (SBQQ) confirmed installed; NOT using Setup > Quote Templates
- [ ] All `SBQQ__TemplateSection__c` records have correct `SBQQ__Type__c` and `SBQQ__DisplayOrder__c`
- [ ] All conditional sections have a valid `SBQQ__ConditionalPrintField__c` pointing to a real field on `SBQQ__Quote__c`
- [ ] Line Items content type has corresponding `SBQQ__LineColumn__c` records; column widths sum to 100
- [ ] All HTML content uses inline styles only (no `<style>` blocks, no CSS classes)
- [ ] All images are under 5 MB; logo renders correctly in Preview
- [ ] "Preview" button used to verify the PDF before deploying; line items table is not empty
- [ ] Multi-language templates (if needed) each have a separate `SBQQ__QuoteTemplate__c`; Flow assigns the correct template to the quote

---

## Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. **Standard Setup > Quote Templates produces empty line items in a CPQ org** — Standard quote templates query `QuoteLineItem`. CPQ stores lines in `SBQQ__QuoteLine__c`. Even if the template renders everything else correctly, the line items table will always be blank. You must use the CPQ template objects under the SBQQ namespace.
2. **CSS classes are silently ignored by the XSL-FO renderer** — CPQ converts HTML to XSL-FO for PDF output. CSS classes defined in a `<style>` block, external stylesheets, or `class=""` attributes are stripped before rendering. Only inline `style=""` attributes are applied. This includes font-family, color, padding, and border properties that practitioners assume will carry through.
3. **Conditional Print Field text comparison is exact and case-sensitive** — If the controlling field is a Text field, the section only prints when the value is exactly `"true"` (lowercase). A value of `"True"`, `"TRUE"`, `"Yes"`, or `"1"` will not trigger visibility. This is a common source of sections that never appear in production PDFs.
4. **Images over 5 MB cause silent PDF generation failure** — When an image in the template exceeds 5 MB, CPQ may generate an empty PDF, a PDF without images, or time out without an error message. There is no explicit validation error in Setup. Always compress images and verify size before uploading.
5. **Multi-hop formula fields on SBQQ__QuoteLine__c slow PDF rendering** — Formula fields that traverse multiple relationships (e.g., `SBQQ__Product__r.Family` is fine, but crossing three or more objects) can add significant time to PDF generation per line. On quotes with 50+ lines this becomes noticeable. Use simpler formulas or pre-populate a custom field via Flow instead.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| `SBQQ__QuoteTemplate__c` record | The top-level template; holds name, logo, and terms text |
| `SBQQ__TemplateSection__c` records | Ordered sections defining structure; each has type and optional conditional field |
| `SBQQ__TemplateContent__c` records | Content blocks (HTML, Line Items, Quote Terms, Custom VF) within each section |
| `SBQQ__LineColumn__c` records | Column definitions for Line Items tables; mapped to `SBQQ__QuoteLine__c` fields |
| Template assignment Flow | Record-Triggered Flow that sets `SBQQ__Quote__c.SBQQ__Template__c` for multi-language routing |

---

## Related Skills

- `admin/quotes-and-quote-templates` — standard Salesforce quote templates for non-CPQ orgs; covers Setup > Quote Templates and `QuoteLineItem`-backed PDFs
- `apex/quote-pdf-customization` — Visualforce-based custom PDF rendering; use when CPQ Custom content type (Visualforce page) is needed for Apex-driven layouts
- `architect/cpq-vs-standard-products-decision` — decision framework for whether an org should use CPQ or standard Products/Quotes