Home / admin / quotes-and-quote-templates

quotes-and-quote-templates

Use when configuring standard Salesforce Quotes, building quote templates for PDF generation, emailing quotes, syncing quotes to opportunity products, or setting up discount approvals on quotes.

• v1.1.0
• Salesforce Spring '25+
• Updated 2026-09-05
• Reliability
• User Experience
• Operational Excellence

• quotes
• quote-templates
• pdf-generation
• quote-sync
• discount-approval
• opportunity-products

Open the skill folder on GitHub

Quotes and Quote Templates

Use this skill when a practitioner needs to configure standard Salesforce Quotes: creating quotes from opportunities, building PDF-ready quote templates, emailing quotes, managing quote sync with opportunity products, or wiring up a discount approval process. This skill does NOT cover CPQ (SBQQ) configuration — route those requests to the architect/cpq-vs-standard-products-decision skill.

Before Starting

Gather this context before working on anything in this domain:

• Quotes must be enabled: Confirm Quotes is turned on in Setup > Quote Settings. Without this, the Quotes related list will not appear on Opportunities and the Quote object will not be accessible.
• Edition requirement: Standard Quotes are available in Performance, Unlimited, Enterprise, and Developer editions; Professional Edition requires an add-on. Verify the org edition before designing any Quote-based workflow. UNVERIFIED (2026-09-05): the edition matrix is a help.salesforce.com table and is not stated in the Metadata API guide or the Object Reference; both simply describe QuoteSettings.enableQuote as the switch (api_meta.txt L124911). Confirm the edition against the org's own Company Information page rather than from memory.
• CPQ vs Standard: The most common wrong assumption is that standard Quotes and CPQ Quotes are the same product on the same object. Standard Quotes use QuoteLineItem; CPQ uses SBQQ__QuoteLine__c. Standard quote templates cannot render CPQ quote lines. Never mix them without explicit confirmation of which product is licensed.
• Custom field gap: Custom fields on Opportunity or OpportunityLineItem do NOT automatically appear on Quote or QuoteLineItem. There is no declarative mapping; you need custom Apex or a Record-Triggered Flow.
• Sync constraint: Only one quote per opportunity can be synced at a time. Opportunity.SyncedQuoteID holds that quote's ID; setting it starts sync, nulling it stops sync, and the ID "has to be for a quote that is a child of the opportunity" (object_reference.txt L192906–192912). The mirror flag on the quote side, Quote.IsSyncing, is read-only (Defaulted on create, Filter).
• No template metadata type: Quote templates cannot be deployed. QuoteTemplate appears in the Metadata API Developer Guide once, as a SummaryLayoutStyle enum value on Layout (api_meta.txt L83162–83170), not as a component. Everything around the template deploys; the template is rebuilt in Setup per org. Plan the manual step into the release — see references/gotchas.md Gotcha 11.
• The discount you can write is on the line, not the header: Quote.Discount is a derived roll-up with properties Filter, Nillable, Sort and no Create/Update (object_reference.txt L239578–239592). QuoteLineItem.Discount is the editable one, 0–100 (object_reference.txt L240758–240767). Any design that "resets the discount" must target the lines.

Questions to Ask Before Configuring

Ask these before opening Setup. Each one maps to a documented platform behaviour that silently changes the design, and each maps to a gotcha in references/gotchas.md.

What a proper configuration adds over just enabling Quotes and drawing a template: the statuses that may email a PDF are declared in deployable metadata rather than enforced by a validation rule that the Email Quote action can route around, the approval's reject branch writes to a field that is actually writable, the manual template rebuild is a scheduled release task instead of a cutover surprise, and the synced quote can be reconciled against the opportunity's products with a query rather than by eye.

Core Concepts

Quote Sync and the SyncedQuoteId Field

Quote sync is the mechanism by which quote line items and opportunity products stay in alignment. When a quote is synced to its parent opportunity, the Opportunity.SyncedQuoteId is set to the quote's ID. From that point:

• Changes to quote line items flow down to opportunity products (OpportunityLineItem).
• Changes to opportunity products flow back up to quote line items.
• The sync is bidirectional but only for the single synced quote.

Only one quote can be synced to an opportunity at a time. If you start syncing a second quote, sync on the first quote stops and the first quote's lines diverge from the opportunity from that moment forward. This is a platform constraint, not a configuration option.

Stopping sync does not delete or revert data — it simply stops the bidirectional update. The opportunity's product lines remain as they were at the time sync was stopped.

Two things about this mechanism are not obvious from the data model:

Quote Templates and PDF Generation

Quote templates control the layout of the PDF that is generated when a user clicks "Generate PDF" or "Save as PDF" on a quote. Templates are configured in Setup > Quote Templates and use a rich-text editor with distinct sections: Header, Body (line items table), and Footer.

The template is not deployable. The Metadata API Developer Guide has no QuoteTemplate component type — the token appears once, as a SummaryLayoutStyle enum value on Layout (api_meta.txt L83162–83170). Templates are rebuilt in Setup in every org. Track them with templates/quote-template-checklist.json, which scripts/check_quotes_and_quote_templates.py lints, and audit what actually shipped through QuoteDocument.DocumentTemplate — "The ID of the template used to generate the document" (object_reference.txt L240440–240448).

Key platform limits:

• Each Text/Image field block in a template has a 32,000-character limit. UNVERIFIED (2026-09-05): this is a Setup-UI limit documented on help.salesforce.com, which cannot be fetched; the nearest grounded 32,000 is Quote.Description (object_reference.txt L239568–239574), a different field. Split long text regardless.
• Templates do not support right-to-left text rendering. UNVERIFIED (2026-09-05): help.salesforce.com only; no API-guide source.
• Templates do not support custom fonts or custom brand color hex codes natively — styling is limited to what the rich-text editor exposes. UNVERIFIED (2026-09-05): help.salesforce.com only; no API-guide source.
• The standard line items table in the template renders QuoteLineItem records only. It cannot render custom objects or CPQ's SBQQ__QuoteLine__c records.
• Line order in the PDF is controlled by QuoteLineItem.SortOrder — the value "determines the order in which a quote line item appears in the Quote Line Items related list and the Quote PDF" (object_reference.txt L241417–241425). It is writable (Create, Filter, Group, Nillable, Sort, Update), so line order is a configurable outcome, not luck.

The template can include standard and custom fields from the Quote object in the header/footer. Fields from QuoteLineItem are available in the body table columns. Fields from Opportunity are NOT automatically available — they must be mapped to a Quote field first. Note that Quote.GrandTotal cannot be used in a Quote formula field at all: it "is not directly referenceable or usable in custom formula fields on the Quote object" and the error names the wrong cause — "Field GrandTotal does not exist. Check spelling." (object_reference.txt L239630–239637). Roll up from QuoteLineItem instead.

Emailing Quotes

A quote PDF can be emailed to the contact named on the quote directly from the quote record using the "Email Quote" button. The email uses the default quote email template unless customized. Key behaviors:

• The email is logged as an activity on both the Quote and the related Opportunity.
• The recipient defaults to the contact in the Quote.ContactId field.
• The attached PDF is re-generated at time of send, using the quote template currently selected on the quote record.
• Org-wide email settings (deliverability, from address) apply to quote emails exactly as they do to all outbound email.
• Which statuses may email at all is declared per picklist value. StandardValue.allowEmail on the QuoteStatus standard value set "indicates whether this value lets users email a quote PDF (true), or not (false). This field is only relevant for the Status field in quotes." Available in API version 18.0 and later (api_meta.txt L47538–47541). This is deployable metadata, it is the intended control, and it is the reason most "block sending before approval" validation rules are unnecessary. See references/metadata-examples.md §2.

Discount Approvals on Quotes

Standard Approval Processes can be built on the Quote object using the same mechanism as any other object. Common patterns:

• Trigger approval when Quote.Discount exceeds a threshold. This works as an entry criterion because the field is filterable.
• Lock the quote record on submission so it cannot be edited during review.
• Drive approver routing from the quote owner's manager (Quote is an ownable object — QuoteOwnerSharingRule and QuoteShare exist from API 41.0, object_reference.txt L240148–240152) or from a named user.
• Set Status to a value whose allowEmail is false while the quote is in review, and to one whose allowEmail is true on approval. That is the send gate.

The trap in the reject branch: you cannot write Quote.Discount back. It is Filter, Nillable, Sort with no Create and no Update, and is defined as a roll-up of the line items' discounted totals (object_reference.txt L239578–239592). Point the rejection field update at QuoteLineItem.Discount (Create, Filter, Nillable, Sort, Update, 0–100 — object_reference.txt L240758–240767) or at QuoteLineItem.DiscountAmount, or reset the lines from a flow. The same applies to GrandTotal, Subtotal, TotalPrice, LineItemCount, QuoteNumber, IsSyncing and AccountId; Tax and ShippingHandling are writable.

Because Quotes are children of Opportunities, consider whether the approval should block the opportunity stage progression too — if so, add a validation rule on Opportunity that prevents stage advancement while the related quote is pending approval.

Common Patterns

Pattern: Single Synced Quote as Order of Record

When to use: An opportunity has multiple quote drafts explored across different pricing scenarios, and the team wants one canonical quote that drives opportunity revenue.

How it works:

1. Create multiple quote records from the opportunity for different scenarios.
2. When a scenario is selected, click "Start Sync" on that quote. This sets Opportunity.SyncedQuoteId.
3. All line item edits from this point happen on the synced quote, and the opportunity products update automatically.
4. Before closing the opportunity, confirm the synced quote reflects the final agreed terms.
5. Optionally generate the PDF and email it to the customer from the same quote record.

Why not the alternative: Editing opportunity products directly while a quote is synced can cause conflicts. Always edit from the synced quote's line items when sync is active.

Pattern: Multi-Section Quote Template with Custom Header Fields

When to use: The business wants the quote PDF to include information from the related Opportunity or Account (e.g., Account Industry, Opportunity source, custom agreement terms).

How it works:

1. Create custom fields on the Quote object that mirror the Opportunity/Account fields needed.
2. Populate those fields via a Flow triggered on Quote creation/update from the parent Opportunity.
3. In Setup > Quote Templates, add those custom Quote fields to the Header section of the template.
4. The PDF will render the latest values of those fields at generation time.

Why not the alternative: You cannot reference Opportunity.Account.Industry directly in a quote template field merge. The template's field picker only surfaces Quote and QuoteLineItem fields. Formula fields on Quote that reference parent objects work for simple cases, but complex cases require the Flow-based population approach.

Pattern: Discount Approval Gate on Quote

When to use: Sales reps can offer discounts up to a threshold (e.g., 10%) without approval; anything above that requires manager sign-off.

How it works:

1. Build a standard Approval Process on the Quote object.
2. Entry criteria: Quote.Discount > 10.
3. Lock the record on submission.
4. Route to the quote owner's manager or a specific approver queue.
5. Hold Status on a value whose allowEmail is false (In Review) for the duration, so the PDF cannot be sent mid-approval.
6. On approval, unlock the quote and set Status to a value whose allowEmail is true (Approved).
7. On rejection, unlock the quote and reset the line-level discount — a flow over the quote's QuoteLineItem records writing Discount (or DiscountAmount), never a field update on Quote.Discount.

Why not the alternative: Doing this only on the Opportunity stage misses scenarios where the discount is embedded in the quote line items rather than the header discount field. And the naive version of step 7 — a field update on Quote.Discount — cannot be built: the field has no Create and no Update property because it is a roll-up of the lines (object_reference.txt L239578–239592). The header number moves only when the lines move.

Decision Guidance

Recommended Workflow

1. Establish which quoting product this org runs, then read the guides. ls for SBQQ__* in the source, or query SBQQ__Quote__c. If CPQ owns the quote lines, stop and route to admin/cpq-quote-templates or architect/cpq-vs-standard-products-decision — standard templates render QuoteLineItem and produce an empty body for CPQ quotes. If standard Quotes, read references/gotchas.md before designing anything; Gotchas 5, 8, 9, 11 and 13 each invalidate a design that looks correct on paper.
2. Answer the seven questions above and write the answers down. The allowEmail question and the schedule question in particular change what you build, not just how you build it. Fill in templates/quotes-and-quote-templates-template.md as you go.
3. Build the deployable layer from references/metadata-examples.md. In order: settings/Quote.settings-meta.xml (§1) → the complete QuoteStatus standard value set with allowEmail per status (§2) → custom mirror fields on Quote (§3) → validation rules (§4) → layout (§6) → permission-set FLS. Retrieve StandardValueSet:QuoteStatus before editing it; a partial file deactivates every status you omit.
4. Build the template by hand in a sandbox and record it in templates/quote-template-checklist.json. There is no metadata type, so this JSON file is the reviewable artefact. Set sections.line_items.sort_field to SortOrder, list the header's Quote fields, and leave verified_in_org.* false until each has actually been done in an org.
5. Run the checker against the manifest. python3 scripts/check_quotes_and_quote_templates.py --manifest-dir force-app/main/default. It fails the manifest on: enableQuote not true when Quote metadata ships; standard statuses omitted from the value set; statuses referenced by rules or flows that the value set does not define; GrandTotal in a Quote formula; flows writing read-only Quote fields; a stray *.quoteTemplate-meta.xml; and a checklist whose statuses_allowing_email disagrees with the deployed allowEmail values. Use --quiet in CI to gate on ERROR only.
6. Test the three things that fail silently. (a) Email Quote from a status with allowEmail false — the action must not be offered. (b) Edit Quantity on a synced line whose HasQuantitySchedule is true — confirm with the reconciliation SOQL in references/metadata-examples.md §8b that the value did not move, and that nobody got an error. (c) Submit and reject a discount approval as a non-admin user, then verify the discount actually reversed on QuoteLineItem, not just on the header roll-up.
7. Reconcile and hand over. Run the three queries in §8b (synced quote vs. opportunity products; quote lines with a null OpportunityLineItemId; more than one quote claiming to sync per opportunity) and the QuoteDocument audit query in §8c. Deliver the Review Checklist, the filled checklist JSON, and a named owner for the next template rebuild.

Review Checklist

Run through these before marking work in this area complete:

• [ ] Quotes is enabled in Setup > Quote Settings and visible on the Opportunity page layout
• [ ] Quote template generates a valid PDF in sandbox with real opportunity and product data
• [ ] Any custom fields needed on the PDF are present on the Quote object and populated correctly (via formula or Flow)
• [ ] Only one quote is ever set as synced at a time; process documented for switching sync
• [ ] Email Quote tested end-to-end: correct PDF attached, correct recipient, activity logged on both Quote and Opportunity
• [ ] If discount approval is configured: tested with a non-admin user, record locking verified, and the rejection action writes QuoteLineItem.Discount — not Quote.Discount, which is read-only
• [ ] No CPQ-related QuoteLineItem assumption introduced (standard templates do not render SBQQ__QuoteLine__c)
• [ ] Template character limits not exceeded (32,000 chars per Text/Image field)
• [ ] QuoteStatus value set deployed complete, with allowEmail set explicitly on every status
• [ ] python3 scripts/check_quotes_and_quote_templates.py --manifest-dir <dir> returns no ERROR lines
• [ ] templates/quote-template-checklist.json filled in, no REPLACE ME placeholders, verified_in_org all true
• [ ] Manual template rebuild booked into the release plan for every target org (no metadata type exists)
• [ ] Reconciliation queries run: no quote line on a syncing quote has a null OpportunityLineItemId, and no opportunity has two quotes claiming to sync

Salesforce-Specific Gotchas

1. Only one synced quote per opportunity — The Opportunity.SyncedQuoteId can hold exactly one quote ID. Starting sync on a second quote silently stops sync on the first. Teams often discover this mismatch only when closing the opportunity.
2. Standard quote templates cannot render CPQ quote lines — If CPQ is installed, quote lines live in SBQQ__QuoteLine__c, not QuoteLineItem. A standard template on a CPQ quote generates a PDF with a blank line items section.
3. Custom fields on Opportunity/OpportunityLineItem do not auto-map to Quote/QuoteLineItem — There is no declarative field mapping. Creating a custom field on Opportunity and expecting it to copy to Quote will not work without custom Apex or a Flow.
4. Quote.Discount cannot be written — It is a derived roll-up (Filter, Nillable, Sort; object_reference.txt L239578–239592). An approval rejection that "resets the discount" must target QuoteLineItem.Discount. UNVERIFIED (2026-09-05): this skill previously claimed System Administrators bypass approval entry criteria; no source in the Metadata API guide or Object Reference supports that, so do not repeat it. Still test as a non-admin — admins can edit approval-locked records, so an admin run never exercises the lock.
5. Quote PDF re-generates at email send time — If a quote template is modified after a PDF was saved on the record, clicking "Email Quote" generates a NEW PDF using the updated template. Lock the template before PDFs are sent to customers.
6. SyncedQuoteID is read-only in an Apex trigger — "Read only in an Apex trigger" (object_reference.txt L192906–192912). Trigger-based sync automation compiles, deploys, and does nothing.
7. Scheduled lines swallow edits — With a quantity or revenue schedule on the synced opportunity line, "the update isn't rejected but the updated value is ignored" (object_reference.txt L240848–240870).
8. A partial QuoteStatus deploy deactivates omitted statuses — "If picklist values are missing from a component definition, they get deactivated when deployed" (api_meta.txt L47481–47483). Always retrieve first.
9. There is no QuoteTemplate metadata type — Templates are Setup-only and rebuilt per org (api_meta.txt L83162–83170).

Output Artifacts

Reference Files

Related Skills

• admin/cpq-quote-templates — Use when the org's quote lines are SBQQ__QuoteLine__c and the document is produced by a CPQ Document Template. NOT for QuoteLineItem or Setup > Quote Templates.
• admin/quote-to-cash-requirements — Use when the question spans quote → order → contract → invoice rather than the quote artefact itself.
• architect/cpq-vs-standard-products-decision — Use when the org is evaluating CPQ vs standard Quotes, or when CPQ is already installed and quote line rendering on PDFs is failing. NOT for standard Quotes configuration.
• admin/approval-processes — Use when the discount approval process on quotes becomes complex (multi-step, exception paths, delegation). NOT for quote sync or template design.
• admin/products-and-pricebooks — Use when the product catalog, pricebook structure, or pricing rules are the root cause of incorrect quote line item amounts. NOT for quote template layout.
• admin/email-templates-and-alerts — Use when the quote email template itself needs redesign or the email deliverability configuration is the issue. NOT for quote PDF template layout.
• admin/opportunity-management — Use when the relationship between opportunities, products, and quote sync needs architectural review as part of a broader sales process redesign.

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/metadata-examples.md
• references/well-architected.md
• templates/quote-template-checklist.json
• templates/quotes-and-quote-templates-template.md
• scripts/check_quotes_and_quote_templates.py