Proposal · Quotes API
Quotes should be
programmable.
Marketing emails and website pages are built from templates you can fill over the API. Quotes are not. This page sets out why that gap costs real projects, how quote templates should be structured, how their CSS should cascade, and what the API calls should look like — with the code. Written for HubSpot's quoting team.
01 The gap
A quote is the one document you cannot write.
Everything around a quote is API-driven: the deal, the contacts, the line items, the status, the signature state. The quote itself — the sections, the words, the layout the buyer reads — is authored in the editor and nowhere else.
| Capability | Marketing email | Website page | Quote today |
|---|---|---|---|
| Template defined in code | Yes | Yes | Modules yes, template layout no |
| Create from a template over the API | Yes | Yes | Yes — properties and associations only |
| Place modules and set every field value | Yes | Yes | No |
| Read the content back | Yes | Yes | No |
| Update one module after creation | Yes | Yes | No |
| Clone and translate | Yes | Yes | No |
What this costs in practice. A quote that is generated rather than hand-built — from a customer's purchase order, an RFP, a CPQ configuration, a pricing engine, or an AI assistant drafting the narrative — can get its line items, price, parties and terms into HubSpot, and then stops. The cover letter, the scope description, the case-study block, the team page and the appendix still need a person in the editor. The one content property a quote exposes is hs_cover_letter.
Who it hits.
- Automation. A deal reaches a stage, a workflow or an integration creates the quote — and it arrives as an empty shell that someone must finish by hand.
- AI assistants. Agents can already read the CRM and create the quote record. They cannot write the proposal text into the document the buyer receives.
- Template governance. Teams that run dozens of quote templates cannot diff, version, test or promote them between a sandbox and production, because the layout is not an artefact.
- Localisation and migration. Emails and pages can be cloned per language over the API. A quote cannot, and a move from a legacy quote to a new template means retyping.
Nothing here asks for a new product. Coded quote modules already exist, already have typed fields, and already render on the live quote. What is missing is the same thing emails and pages have: a way to say which modules, in which places, with which values.
02 What we checked
How emails and pages work today.
Before proposing a quote model, we tested the assumption it rests on: that email and page templates mix fixed content, drag-and-drop areas and fixed modules, and that the API can reference the template and fill every module field. Half of that is right, and the half that is wrong changes the design.
| Assumption | Result | Source |
|---|---|---|
| A template can hardcode a header, then a drag-and-drop area, then a footer | Holds. | HubSpot's custom email template page |
| The drag-and-drop area can be pre-filled with default modules | Holds. The area's body supplies the defaults; modules sit inside a section and column. | Same page |
| An email template can have several drag-and-drop areas | Does not hold in email. | The same page: “Custom email templates can only contain one drag and drop area.” dnd_row is also unsupported in email. |
| Website and landing page templates can have several named areas | Holds — this is where “fixed, area, fixed module, empty area, fixed footer” is possible. | Standard dnd_area behaviour on page templates; not re-fetched for this page |
| The API references the template and sets values for every module field | Holds for emails and for named modules on pages. | Live-tested on portals, June–July 2026 |
| The API can set values for the default modules inside a template's drag-and-drop area on a page | Does not hold. Defaults render but are never written into the page's layout, so there is nothing to address. | Live-tested on a portal, June 2026 |
Email: one area, fixed content around it
An email on a coded template is created with the template path, the layout of the drag-and-drop area, and a widgets map. The layout lists widget IDs per column in render order; the map holds each module's numeric module_id and its field values.
{
"name": "Autumn newsletter",
"content": {
"templatePath": "brand/email/templates/newsletter.html",
"flexAreas": {
"main": {
"sections": [{
"id": "section_main",
"style": { "backgroundType": "CONTENT" },
"columns": [{
"id": "column_main",
"width": 12,
"widgets": ["module_0001", "module_0002"]
}]
}]
}
},
"widgets": {
"module_0001": {
"type": "module",
"module_id": 217438723609,
"body": { "headline": "Doors open at 19:00", "hs_enable_module_padding": false }
},
"preview_text": { "type": "text", "body": { "value": "Preview text here" } }
}
}
}
Two details matter for quotes. The module is addressed by a portal-specific numeric ID, which differs on every portal and must be fetched from the module's meta.json after each upload. And everything outside the drag-and-drop area — the header, the footer — is part of the template and needs no API call at all.
Pages: named modules are addressable, default modules are not
On a page the same split exists. A module placed by name in the template ({% module "price_note" path="…" %}) takes its values from widgets.price_note.body. A module placed inside a dnd_area as a default renders on a freshly created page but is not written into layoutSections; the editor materialises it on first open, so the API has no handle to change it. Per-page values for such a module require writing the whole layoutSections yourself.
That trap is the one a quote API must not inherit. A template's defaults should be materialised into addressable widgets at creation time. § 5 builds that into the design.
Quotes: what is documented, and what the editor shows
- Quote templates can be read (
GETand search onquote_templates, filtered onhs_type = cpq_template) but, per HubSpot's CPQ quotes guide, are “created and customized in the HubSpot UI”. - A template can be attached only when the quote is created (association type 286). Setting
hs_template_typetoCPQ_QUOTEuses the default template. - The template's “properties, content, and associations” are copied to the quote as a starting point. Rich-text sections are edited through the editor's source-code menu; the guide advises against HubL in rich text.
- A published quote is locked; changing properties means returning
hs_statustoDRAFTfirst. - Coded modules render on
cpq_templatetemplates only. In the template editor on a demo portal (checked ) a template is one flat, ordered list of sections: HubSpot's native sections (cover letter, header, parties, summary, line items, terms, payments, acceptance), which can be hidden, followed by the coded modules you drag in. There is no “area”, no columns and no way to place a second drop zone. Each custom module can be deleted or locked (“Lock section content on quotes”), and one switch, “Allow users to add modules to quotes”, decides whether quote authors can add more. We found no lock on individual fields. - Every
cpq_templaterecord on that portal has the samehs_cms_template_path,@hubspot/cpq-theme/templates/quote.hubl.html. The file is HubSpot's; what makes one template different from another — its section list, locks and field values — is stored on the record and is not readable over the API. - We found no documented endpoint that reads or writes the modules on a quote or a template. A write scope for templates exists (
cpq.quote_templates.write); what a template contains is not part of that API.
03 The template
A quote template is a layout, not a page.
The model from emails and pages carries over, with two changes: a quote template may have several areas, and a module can be bound to the deal's line items instead of carrying its own copy of the data.
Three slot kinds are enough. The example below is the pattern you described for emails, made possible for quotes by allowing more than one area:
Declaring it
Today the layout is data on the template record, edited by dragging in the editor, and the API cannot see it. The proposal keeps that: the record stays the source of truth and the layout becomes readable and writable over the API (§ 5). A template-as-code file, below, is optional authoring sugar for teams that want the layout in version control: it compiles to the same record, in the way a project's modules compile to portal assets. Because quote modules are already React components in a 2026.09 project, the file is a component too.
import { QuoteTemplate, Fixed, DndArea, DndSection, DndColumn, DndModule }
from '@hubspot/cms-components/quote-template';
export const template = (
<QuoteTemplate
name="Proposal"
stylesheet="./proposal.css" // one stylesheet for the whole document
printStylesheet="./proposal.print.css"
>
<Fixed name="cover" module="QuoteCover"
editableAt="both"
locked={['layout', 'logo']} /> // fields the quote author cannot change
<DndArea name="story">
<DndSection>
<DndColumn width={12}>
<DndModule name="intro" module="QuoteIntro" />
<DndModule name="proof" module="QuoteProof" />
<DndModule name="team" module="QuoteTeam" />
</DndColumn>
</DndSection>
</DndArea>
<Fixed name="pricing" module="QuoteLineItems"
bind={{ lineItems: 'all' }}
locked={['columns']} />
<DndArea name="appendix" /> {/* empty: a drop zone and nothing else */}
<Fixed name="acceptance" module="native:acceptance" removable={false} />
</QuoteTemplate>
);
| Concern | Lives in | Why |
|---|---|---|
| Where things sit | Template | Layout is shared by every quote made from it, and is the thing teams want to version. |
| What the words say | Quote (widgets) | Different on every quote. Template values are only defaults. |
| What it looks like | Template stylesheet; instance override only when set | See § 4. |
| Prices, quantities, parties | CRM objects, bound into modules | One source of truth. A module bound to line items never stores a copy. |
| Who may edit a field | editableAt and locked on the template | Takes the editor's existing per-section lock down to individual fields, so a template can fix the logo and leave the wording open. |
Why allow more than one area. Emails are limited to one, which is why the “fixed, area, fixed, empty area, footer” shape is impossible there. Quotes are closer to pages than emails: long, structured, and often a fixed pricing block between two authored halves. Today a template is one flat list, so a fixed pricing block between two authored halves cannot be protected from an author who is allowed to add modules anywhere. Named areas remove that constraint, and the API addresses each by name.
Why bind rather than copy. A published quote's total is the value the buyer signs, and it is computed from the line items at publish. A pricing module that took its rows from the content API would let the document and the signed value disagree. Binding makes the module's data a read of the CRM; the content API only carries presentation.
04 One cascade
Modules follow the template unless told otherwise.
Today each module carries its own CSS and its own idea of the brand. The native quote theme already publishes design tokens at :root; the missing piece is a template layer between the portal's theme and the individual module.
The four layers
--hsQuotes--* tokens, set in quote settings. Already exists.A module never writes a literal colour into a rule. It reads one chain of custom properties, and each layer only has to define the link it owns:
[data-qm] {
/* instance → template → quote theme → module default */
--_accent: var(--qm-accent, var(--q-accent,
var(--hsQuotes--link--primary__fontColor, #5e6ab8)));
--_radius: var(--qm-radius, var(--q-radius, var(--hsQuotes-rounded--small, 8px)));
--_gap: var(--qm-gap, var(--q-gap, var(--hsQuotes--spacing--16, 16px)));
}
[data-qm="QuoteTeam"] [data-part="card"] {
border-radius: var(--_radius);
border: 1px solid var(--_accent);
padding: var(--_gap);
}
The platform emits the stylesheets into named cascade layers in a fixed order, so nobody fights specificity:
@layer hsq-reset, hsq-theme, hsq-module, hsq-template, hsq-print;
/* hsq-theme the portal's quote theme tokens (exists today)
hsq-module every module's CSS, deduplicated per module type
hsq-template the template's stylesheet
hsq-print the template's print stylesheet (the PDF is a print render)
Instance overrides are inline custom properties: unlayered, so they win. */
The template's own stylesheet
The template sets tokens once. Every module that follows the chain picks them up, including modules written by other people that the template author has never opened. A rule can also reach a named module through two stable hooks the platform guarantees: data-qm (the module type) and data-part (a named region the module exposes, in the manner of CSS parts).
.hsq-document {
--q-accent: #0b5cad;
--q-radius: 2px;
--q-gap: 24px;
}
/* A rule for one named slot, not one module type */
[data-slot="pricing"] [data-part="total-row"] {
font-weight: 700;
border-top: 2px solid var(--q-accent);
}
/* Template-wide: every module's heading */
[data-qm] [data-part="heading"] { letter-spacing: -0.01em; }
Proposed · templates/proposal.print.css
@media print {
[data-part="web-only"] { display: none; }
[data-slot="appendix"] { break-before: page; }
}
Unless otherwise specified
The override rule is about absence. A style field on a module has three states, and the API carries all three:
| In the request | Meaning | Rendered as |
|---|---|---|
| Key omitted | Inherit from the template. Also the default for a new module. | No inline property; the chain resolves to layers 3, 2, 1. |
null | Reset to inherit. Removes an earlier override. | Inline property removed. |
| A value | Override on this module of this quote only. | --qm-accent: #b00020 inline on the module root. |
In the editor this is the “Use template style” toggle that sits beside every style field and is on by default. Without it, a module saves its default value as if the author had chosen it, and the template can never change it again. That is how a restyled template ends up leaving old documents behind.
import { ModuleFields, FieldGroup, ColorField, NumberField } from '@hubspot/cms-components/fields';
import { instanceVars } from '@hubspot/cms-components/quote-template';
export const fields = (
<ModuleFields>
<FieldGroup name="styles" label="Style" tab="STYLE">
<ColorField name="accent" label="Accent" inheritFrom="--q-accent" />
<NumberField name="radius" label="Corner radius" inheritFrom="--q-radius" unit="px" />
</FieldGroup>
</ModuleFields>
);
export function Component({ fieldValues }: any) {
// Returns only the properties that were actually set. Unset fields add nothing.
const vars = instanceVars(fieldValues.styles, { accent: '--qm-accent', radius: '--qm-radius' });
return <section data-qm="QuoteTeam" style={vars}>…</section>;
}
A field with inheritFrom tells the editor which template token to preview as the placeholder, and tells the API which key means “inherit”. The platform, not the module author, owns the three-state behaviour — so it cannot be implemented wrongly.
05 The API
The email model, for quotes.
The shape is deliberately the one marketing emails already use — areas, sections, columns, a widgets map — so anyone who has automated an email already knows it. The two additions are materialised defaults and an explicit lock-state contract.
| Call | Purpose | Notes |
|---|---|---|
GET /crm/quote-templates/{ver}/{id}/layout | Read a template's slots, defaults, locks, stylesheet | The discovery call: tells a client which names exist. |
PUT /crm/quote-templates/{ver}/{id}/layout | Replace a template's layout | Under cpq.quote_templates.write. Same body as the read; the editor and the API edit one record. |
POST /crm/objects/{ver}/quotes | Create a quote; accepts an optional content body | Existing call, extended. One request, so the quote initialises with its content. |
GET /crm/quotes/{ver}/{id}/content | Read areas and widgets | ?resolved=true adds inherited values and defaults. |
PUT /crm/quotes/{ver}/{id}/content | Replace all content | Requires If-Match. |
PATCH /crm/quotes/{ver}/{id}/content | Change some widgets or areas | JSON Merge Patch. Requires If-Match. |
POST …/content/areas/{area}/sections | Insert a section at an index | For authoring without rewriting the whole area. |
POST …/content/validate | Dry run of any of the above | Field-level errors, nothing written. |
POST …/content/preview | Render to a URL as web or PDF | Works on a draft; the link is private and expires. |
1 · Discover the template
Proposed · GET /crm/quote-templates/2026-09/48210973/layout{
"id": "48210973",
"name": "Proposal",
"hs_type": "cpq_template",
"stylesheet": "/proposal.css",
"slots": [
{ "name": "cover", "kind": "fixed", "modulePath": "@projects/quote-collection/QuoteCover",
"editableAt": "both", "locked": ["layout", "logo"] },
{ "name": "story", "kind": "area",
"defaults": ["intro", "proof", "team"] },
{ "name": "pricing", "kind": "fixed", "modulePath": "@projects/quote-collection/QuoteLineItems",
"bind": { "lineItems": "all" }, "locked": ["columns"] },
{ "name": "appendix", "kind": "area", "defaults": [] },
{ "name": "acceptance", "kind": "fixed", "modulePath": "native:acceptance", "removable": false }
],
"modules": {
"QuoteTeam": { "moduleId": 217438723711, "schema": "/cms/modules/2026-09/217438723711/fields" }
}
}
Modules are referenced by modulePath, with the numeric moduleId accepted as an alternative. Emails force a client to look up a portal-specific ID after every upload; a path is the same on a sandbox and on production, so one script works on both.
2 · Create a quote with its full content
The existing create call, with content added. Properties and associations are exactly as documented today: template association 286, hs_template_type CPQ_QUOTE for coded templates, line items as the quote's own copies.
{
"properties": {
"hs_title": "Proposal — warehouse automation, phase 2",
"hs_template_type": "CPQ_QUOTE",
"hs_expiration_date": "2026-12-31",
"hs_currency": "EUR",
"hs_language": "en"
},
"associations": [
{ "to": { "id": "48210973" }, "types": [{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 286 }] },
{ "to": { "id": "9154432101" }, "types": [{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 64 }] },
{ "to": { "id": "7720031" }, "types": [{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 702 }] }
],
"content": {
"areas": {
"story": {
"sections": [{
"id": "s_story_1",
"columns": [{ "id": "c1", "width": 12, "widgets": ["intro", "proof", "team", "scope"] }]
}]
},
"appendix": {
"sections": [{
"id": "s_app_1",
"columns": [{ "id": "c1", "width": 12, "widgets": ["assumptions"] }]
}]
}
},
"widgets": {
"cover": {
"type": "module",
"body": {
"eyebrow": "Proposal",
"title": "Warehouse automation, phase 2",
"subtitle": { "text": "Prepared for the operations board", "emphasis": false },
"hero_image": { "src": "https://example.com/files/hero.jpg", "alt": "Warehouse aisle", "width": 1600, "height": 900 }
}
},
"intro": {
"type": "module",
"body": {
"heading": "What we heard",
"body": "<p>Pick accuracy is at 97.1% and the target is 99.5%.</p><p>Phase 2 closes that gap.</p>"
}
},
"proof": {
"type": "module",
"body": {
"items": [
{ "metric": "-38%", "label": "Mis-picks", "source_url": "https://example.com/case/1" },
{ "metric": "6 weeks", "label": "Go-live", "source_url": "https://example.com/case/2" }
]
},
"style": { "accent": "#b00020" }
},
"team": {
"type": "module",
"body": {
"members": [
{ "name": "A. Visser", "role": "Delivery lead", "photo": { "src": "https://example.com/p/av.jpg", "alt": "" } },
{ "name": "M. Okafor", "role": "Solution architect", "photo": { "src": "https://example.com/p/mo.jpg", "alt": "" } }
]
}
},
"scope": {
"type": "module",
"modulePath": "@projects/quote-collection/QuoteIntro",
"body": { "heading": "Scope", "body": "<ul><li>Conveyor retrofit</li><li>Scanner integration</li></ul>" }
},
"assumptions": {
"type": "module",
"modulePath": "@projects/quote-collection/QuoteTerms",
"body": { "terms": [{ "title": "Access", "text": "Site access on weekdays 06:00–18:00." }] }
}
}
}
}
What this one request shows:
- Fixed slots (
cover,pricing,acceptance) appear inwidgetsonly if you set values. They never appear inareas, because their position is the template's. - Area contents are listed by widget ID in render order, exactly as an email's
flexAreasdo. Thestoryarea takes the template's three defaults and adds a fourth,scope, by giving it amodulePath— a module the template did not list. proofoverrides the accent; no other module sets a style, so all of them inherit the template's.- The pricing module is absent, because it is bound to the quote's line items. Prices are the CRM's business.
- Field values use the module's own field names and types — group, repeater, image, rich text, link — validated against the module's field schema.
3 · Read it back, with defaults materialised
This is the answer to the page-template trap in § 2. Whatever the template supplied is written into the quote at creation, so every widget has an ID and every value can be read and changed. With resolved=true the response also shows what each style field currently resolves to and where the value came from.
{
"version": "v3",
"templateId": "48210973",
"areas": { "story": { "sections": [ … ] }, "appendix": { "sections": [ … ] } },
"widgets": {
"proof": {
"type": "module",
"modulePath": "@projects/quote-collection/QuoteProof",
"body": { "items": [ … ] },
"style": { "accent": "#b00020" },
"resolved": {
"style": {
"accent": { "value": "#b00020", "from": "instance" },
"radius": { "value": "2px", "from": "template" },
"gap": { "value": "24px", "from": "template" }
}
}
}
}
}
4 · Change one widget
A merge patch touches only what it names. Setting a style key to null returns the module to the template's value.
PATCH /crm/quotes/2026-09/48831205/content
If-Match: "v3"
Content-Type: application/merge-patch+json
{
"widgets": {
"intro": { "body": { "heading": "What we heard on 12 November" } },
"proof": { "style": { "accent": null } },
"team": { "body": { "members": [ { "name": "A. Visser", "role": "Programme lead", "photo": { "src": "https://example.com/p/av.jpg", "alt": "" } } ] } }
}
}
Repeaters, like members above, are replaced whole — a merge patch cannot address array elements, and silently merging them is how entries go missing. A client that wants to append reads, changes and writes the array under If-Match.
5 · Insert a section into an area
Proposed · POST /crm/quotes/2026-09/48831205/content/areas/appendix/sections{
"index": 0,
"section": {
"id": "s_app_2",
"columns": [
{ "id": "c1", "width": 6, "widgets": ["glossary"] },
{ "id": "c2", "width": 6, "widgets": ["contacts"] }
]
},
"widgets": {
"glossary": { "type": "module", "modulePath": "@projects/quote-collection/QuoteFAQ", "body": { "items": [ … ] } },
"contacts": { "type": "module", "modulePath": "@projects/quote-collection/QuoteTeam", "body": { "members": [ … ] } }
}
}
6 · Validate before writing
Quote content is read by buyers and signed. A dry run belongs in every integration's test suite, and it is what an AI assistant should call before it commits a draft.
{
"valid": false,
"errors": [
{ "path": "widgets.team.body.members[1].photo.src", "code": "FIELD_TYPE_MISMATCH",
"message": "Expected an https URL or a file ID; received null." },
{ "path": "widgets.cover.body.layout", "code": "FIELD_LOCKED_BY_TEMPLATE",
"message": "Field 'layout' is locked by template 48210973." },
{ "path": "areas.pricing", "code": "UNKNOWN_AREA",
"message": "'pricing' is a fixed slot, not an area. Areas: story, appendix." }
]
}
7 · Preview and publish
Publishing stays what it is today — a PATCH of hs_status after the quote has finished initialising, with the same hs_locked polling. Preview closes the loop before that point: an agent or a pipeline can render the draft to PDF and look at it.
{ "format": "pdf" }
→ 200
{ "url": "https://f.hubspotusercontent-eu1.net/preview/…/proposal.pdf", "expiresAt": "2026-11-18T15:00:00Z", "pages": 7 }
The same flow in one script
Proposed · Node 24, no dependenciesconst api = (path, init = {}) => fetch(`https://api.hubapi.com${path}`, {
...init,
headers: { Authorization: `Bearer ${process.env.HS_TOKEN}`, 'Content-Type': 'application/json', ...init.headers },
}).then(async (r) => { if (!r.ok) throw Object.assign(new Error(r.statusText), { body: await r.json() }); return r.json(); });
const layout = await api(`/crm/quote-templates/2026-09/${TEMPLATE_ID}/layout`);
const areas = layout.slots.filter((s) => s.kind === 'area').map((s) => s.name); // ['story', 'appendix']
// 1. Check first
const check = await api(`/crm/objects/2026-09/quotes/validate`, { method: 'POST', body: JSON.stringify(payload) });
if (!check.valid) throw new Error(JSON.stringify(check.errors));
// 2. Create with content in one request
const quote = await api(`/crm/objects/2026-09/quotes`, { method: 'POST', body: JSON.stringify(payload) });
// 3. Wait for initialisation (existing behaviour: poll hs_locked, not hs_status)
// 4. Preview, then publish with PATCH hs_status = APPROVAL_NOT_NEEDED
Behaviour the API has to define
| Situation | Proposed behaviour |
|---|---|
| Content write on a published quote | 409 QUOTE_LOCKED, naming hs_status. The existing unpublish → edit → republish cycle applies; content writes never unlock a quote implicitly. |
| Concurrent edit (editor and API) | If-Match on every write; 412 when stale, with the current version. |
| Field locked by the template | 422 FIELD_LOCKED_BY_TEMPLATE. Reads are never refused. |
| Template changes after quotes exist | Quotes keep their materialised content. Style that was never overridden follows the template's stylesheet; layout does not move. |
| Widget with unknown module | 422 UNKNOWN_MODULE. A module not offered to QUOTE content is rejected, as in the editor. |
| Signed value | Unchanged: a signature captures the published snapshot. Content edits take effect on the next publish. |
| Scopes | Quote read/write for content; template read for layout. Authoring a template stays under cpq.quote_templates.write. |
| Webhooks | quote.content.changed with the version and the changed widget IDs, so an external system can mirror edits made in the editor. |
06 Editor controls
A bound module needs no workaround.
HubSpot's own line-items section shows “Add line item” and “Edit all line items” buttons in the editor. A coded module cannot borrow them.
Every custom line-item module therefore has to rebuild them. The route that works today is to detect the editor's preview frame, reach its parent-frame message bus, and dispatch the editor's own internal actions — one that opens the product library drawer, one that opens the line-item grid. It is undocumented, it can change without notice, it has to fail silently outside the editor, it cannot tell whether the user has permission to read the product library (so some users get a drawer that errors), and every module author re-implements it.
With the model in § 3, none of that is needed. A module declared with bind={{ lineItems: 'all' }} is a line-item module as far as the platform is concerned, and the platform supplies the controls:
export const meta = {
content_types: ['QUOTE', 'QUOTE_BLUEPRINT'],
quote: {
binds: ['lineItems'], // this module renders the quote's line items
editorControls: 'native', // the add / edit-all overlay, drawn by HubSpot
// or: editorControls: 'none' | ['addLineItem', 'editLineItems']
},
};
- The overlay is drawn by the editor, outside the module's DOM, so it is never in the PDF and never needs a print rule.
- It respects the same permissions as the native section, including the greyed-out state for users without product-library access.
- The same declaration tells the editor which sections to refresh when a line item changes, so a custom totals module stays in step.
- Modules that do not bind line items get no controls, as now.
The same principle applies to anything else the editor currently does only for native sections: hover controls, drag handles, the “view tiers” modal. If a module declares what it binds, the editor should treat it like the native one.
07 Around the edges
Smaller things that cost real time.
Each row is behaviour we observed while building quotes over the API and in coded modules on live portals between June and November 2026. None needs the content API; all of them would make it easier to rely on.
| Observed | Why it hurts | Suggested change |
|---|---|---|
Removing a line item from a published quote returns 204 and changes nothing | The caller has no error to branch on; the quote silently keeps the line. | 409 QUOTE_LOCKED, as for any other refused write. |
The quote total does not recompute after a line-item change on a published quote, and hs_quote_amount is read-only | The only recompute is to unpublish and republish. | A recompute action, or an explicit “stale” flag on the quote. |
Republishing straight after unpublishing can fail with DOMAIN_SLUG_EXISTS and leave the quote in draft | Clients have to sleep about a second and retry. | Release the slug synchronously, or accept a republish that reuses it. |
A new quote reports hs_status = DRAFT while initialising; the only signal is hs_locked = true | Polling the obvious property publishes too early and fails. | An explicit hs_initialization_status, or 202 with a status link, plus a webhook when ready. |
hs_quote_link is empty for several seconds after a publish | Integrations that email the link have to poll. | Return the link in the publish response, or emit a quote.published webhook that carries it. |
Omitting hs_template_type against a coded template returns an error that reads “CPQ unsupported” | The natural reaction is to switch to the other template generation, after which every coded module silently stops rendering. | Infer the type from the associated template, or reword the error to name the missing property. |
Signing updates the deal's hs_tcv and hs_acv but not its amount | Pipeline reports disagree with the signed quote until someone patches it. | Make the deal-amount sync a documented setting. |
Line items created through the API have no hs_position_on_quote | Their order on the document is arbitrary until set. | Default to creation order. |
hs_tier_ranges and hs_tier_prices read and write fine but are absent from the properties metadata | Clients cannot discover them or their format. | List them, with a format description. |
The render that produces the PDF has no server-side signal, and hs_pdf_generation_status is empty inside it | Modules must render both variants and let print CSS decide; web-only chrome ends up in the markup. | Expose a render target (web or pdf) in the module context, and give the template a print stylesheet slot (§ 4). |
Creating a template needs cpq.quote_templates.write, and activating one was refused for a private-app token | Template provisioning cannot be scripted, so sandbox-to-production promotion is manual. | Make the scope grantable to private apps, or document who can hold it. |
| The status bar cannot be changed and the document container has a fixed width | Layout-level brand requirements are met with page-wide CSS overrides. | Template-level settings for both, as tokens in the stylesheet layer. |
08 Decisions for you
What we could not decide from outside.
We build on the quote platform; we do not own it. These are the points where the right answer depends on constraints we cannot see.
Several areas, or one?
The editor models a template as one flat list. If areas are a large change, keep the flat list and add “pinned” sections that authors cannot move or remove; that gives most of the benefit, and the API shape in § 5 works with either.
Cascade layers in the PDF renderer
The model assumes the quote and PDF renderers support @layer. If the PDF path does not, the same order can be produced by emitting the stylesheets in sequence — at the cost of specificity discipline.
HubL in rich text
Rich text does not evaluate HubL until publish. Over an API that is a trap: a draft would preview differently from the published quote. We suggest the API rejects HubL expressions in rich text, or evaluates them for preview.
Language variations
Emails have no multi-language routes beyond cloning; pages do. A quote content API makes a clone-and-translate flow possible for quotes on the email model’s terms; true language variations are a separate question.
09 Next
We will test it with you.
We maintain a collection of 2026.09 React quote modules and a documented recipe for creating and publishing quotes over the API, and we would test a prototype of any part of this against them — the three-state style fields and the content read-back first, since they are the smallest slice that proves the model.
Independence. worksby.design is an independent publisher of HubSpot tooling, not affiliated with or endorsed by HubSpot. This page is a proposal from people who build on the quote platform; nothing on it describes planned HubSpot functionality. Facts about HubSpot's current behaviour come from its developer documentation and from calls made against real portals, and are dated above.
Talk to us
Corrections to anything on this page are welcome, especially where the platform behaves differently from what is written here. Get in touch →