> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/sales-and-product-led-growth/cpq.md).

# CPQ

***

## 1. Overview

Younium CPQ (Configure, Price, Quote) is a quoting application built on top of the Younium subscription management platform. It enables sales teams to create structured, priced quotes that can be sent to customers for acceptance and converted directly into Younium subscriptions.

CPQ manages the full commercial journey from initial quote composition through customer signature and subscription creation. It is a standalone application at `cpq.younium.com`, with a sandbox environment at `cpq.sandbox.younium.com`, and is also available as an embedded extension within [HubSpot](/crm-integrations/hubspot.md).

Quotes cover both new business and amendments to existing subscriptions, and the same quote can be priced, approved, signed, and converted without leaving CPQ. CPQ is feature-gated through Younium's entitlement system, so the available feature set depends on the subscription tier of the organisation.

***

## 2. Core Concepts

### Legal Entity

CPQ operates at the **legal entity** level. Each legal entity has its own settings, product catalog sync, quote numbering, branding, approval configuration, and e-signing configuration. A user may belong to one or more legal entities within a tenant. While a legal entity is being set up it can be in **onboarding mode**, which marks it as not yet live (see §20 Onboarding Mode).

### Quote

A quote is the central object in CPQ. It represents a commercial proposal to a customer, containing one or more products with their charges, applicable discounts, subscription terms, and associated contacts. Every quote has a unique quote number made up of a prefix, the year, and a sequence that restarts each year — for example `Q-2026-0001`. The prefix is held per legal entity and is `Q-` unless it has been changed for that entity.

### Product and Charge Plan

Products are sourced from the Younium product catalog and synced into CPQ. Each product has one or more **charge plans**, and each charge plan contains one or more individual **charges**.

How a product is added to a quote depends on its structure. Products with a single charge plan are added at the product level, and all their charges come together. Products with multiple charge plans are added at the charge plan level, so the user selects which plan to use and the charges from that plan become line items. Pricing and quantity can be adjusted on the quote without affecting the catalog.

### Product Bundle

A **product bundle** is a package of products that sellers add to a quote together, at an agreed price and with a bundle discount. Administrators build bundles in CPQ from charge plans in the synced catalog, under **Products → Bundles**, and each legal entity has its own bundles. A bundle's products are either **required**, always part of the bundle, or optional, which the seller can leave out for a customer who does not want them. Younium itself has no bundle object: a bundle reaches Younium as ordinary order lines with a discount, and CPQ recognises it again when the subscription is amended. See [Product Bundles](#product-bundles).

### Rule Set

A **rule set** is a named group of product rules that say which products belong together — for example that one product requires another, or that two products cannot be sold together. Administrators build rule sets under **Products → Rules**, each legal entity has its own, and one active rule set can be marked as the **default**. See [Product Rules](#product-rules).

### Subscription Terms

Each quote specifies the intended subscription structure upon conversion:

* **Subscription type**: Termed (fixed duration) or Evergreen (no fixed end date)
* **Start and end date**: Derived from start date plus initial term months for Termed subscriptions
* **Initial term**: Duration in months; at least one month
* **Renewal term**: Duration in months for automatic renewals; at least one month
* **Auto-renewal**: Whether the subscription renews automatically at the end of the term
* **Notice period**: Months of advance notice required for cancellation before renewal
* **Billing frequency**: The billing interval applied across all charges unless individually overridden

Which subscription types are available is controlled by **Allowed Subscription Types** — Termed Only, Evergreen Only, or Both. Each of the terms above has a legal entity default that pre-fills new quotes. On an amendment, the terms start from the subscription being amended — see [Subscription Terms on an Amendment](#subscription-terms-on-an-amendment).

### Customer Account and Bill-To Account

A quote always has a **customer account** — the party the quote is prepared for. It may additionally have a **bill-to account** (also called the invoice account): a different account that receives the invoices. When the two differ, the bill-to account carries its own address, VAT and organisation number, invoicing email addresses, payment term, and invoice delivery method, and it is the bill-to account that is written to Younium as the subscription's invoice account.

### Approval Group

An **approval group** is a named set of CPQ users who can approve quotes. Each legal entity has a default group, and any active member of an assigned group can approve — approval is not routed to one specific person.

### Integrations

Every connection CPQ makes to another system is managed from one place, **Settings → Integrations**. The page lists each integration as a tile, grouped as Younium, CRM, E-Signing, and Communication, and can be filtered to show all integrations, only those that are connected, or only those that are not. Each tile shows whether the integration is connected: a connected one opens its own settings to manage it, and one that is available but not yet connected offers to connect it. Integrations that cannot be connected yet — Salesforce and Pipedrive among the CRMs — are marked as coming soon.

The Younium integration is always connected, since it is what CPQ quotes from — see [Younium Synchronisation](#20-younium-synchronisation). The others are covered in [E-Signing](#13-e-signing), [Slack](#14-slack), and [HubSpot Integration](#19-hubspot-integration).

### Settings

Configured under **Settings → Quote Settings**.

| Setting                        | Description                                                                                                                                                                           | Default |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| **Allowed Subscription Types** | Which subscription types may be quoted: Termed Only, Evergreen Only, or Both                                                                                                          | Both    |
| **Default Subscription Type**  | Subscription type pre-selected on new quotes, offered when both types are allowed                                                                                                     | Termed  |
| **Initial Term**               | Initial term in months, pre-filled on new quotes                                                                                                                                      | 12      |
| **Notice Period**              | Notice period in months, pre-filled on new quotes                                                                                                                                     | 2       |
| **Auto-Renewal Default**       | Whether new termed subscriptions renew automatically at the end of each term                                                                                                          | On      |
| **Renewal Term**               | Renewal term in months, pre-filled on new quotes                                                                                                                                      | 12      |
| **Default Currency**           | Currency pre-selected on new quotes                                                                                                                                                   | `USD`   |
| **Quote Validity**             | Days a new quote remains valid                                                                                                                                                        | 30      |
| **Enable Sales Orders**        | Lets sellers choose per quote whether it becomes a subscription or a one-time sales order                                                                                             | Off     |
| **Create Subscription As**     | Whether converting an accepted quote creates the Younium subscription as a draft to review, or as an active order                                                                     | Draft   |
| **Display totals in**          | The period quote totals are shown per: Month, Quarter, Year, or Quote billing frequency. It sets the period of the quote's Subtotal and Total — see [Quote Metrics](#6-quote-metrics) | Month   |

Currencies, countries, payment terms, and exchange rates available in CPQ are synchronised from Younium, so the currency list on a quote always matches what the platform accepts.

***

## 3. Quote Lifecycle

Every quote moves through a defined set of statuses. The lifecycle is controlled by a state machine that enforces which transitions are valid at each point.

### Statuses

| Status                 | Stage     | Description                                                                      |
| ---------------------- | --------- | -------------------------------------------------------------------------------- |
| **Building**           | Draft     | Quote is being assembled in the creation wizard. Not visible in the quotes list. |
| **Draft**              | Draft     | Quote is ready for internal review and editing.                                  |
| **Pending Approval**   | Draft     | Quote has been submitted and is awaiting approver review.                        |
| **Rejected**           | Draft     | Rejected by an approver. Returned to the owner for revision.                     |
| **Approved**           | Draft     | Approved and ready to send to the customer.                                      |
| **Sent**               | Presented | Delivered to the customer. Quote page is accessible.                             |
| **Viewed**             | Presented | Customer has opened the quote page at least once.                                |
| **Awaiting Response**  | Presented | Customer sent a message; sales team has not replied.                             |
| **Accepted**           | Presented | Customer accepted the quote (without e-signing).                                 |
| **Awaiting Signature** | Presented | E-signing request sent; no signatures received yet.                              |
| **Partially Signed**   | Presented | At least one signer has signed; waiting for remaining signers.                   |
| **Signed**             | Won       | All parties have signed.                                                         |
| **Converted**          | Won       | Quote has been converted to a Younium subscription.                              |
| **Declined**           | Lost      | Customer declined the quote.                                                     |
| **Expired**            | Lost      | Quote passed its valid-until date without acceptance.                            |
| **Lost**               | Lost      | Closed by the sales team as a lost deal.                                         |

> **Note on Accepted vs Signed:** A quote in *Accepted* status reflects customer intent but is not treated as *Won* in forecasting. Won status requires either full e-signing completion (*Signed*) or conversion to a subscription (*Converted*). This is intentional to prevent premature revenue recognition.

### Lifecycle Stages

Beyond the status, CPQ derives a **lifecycle stage** that combines status with active modifiers:

* **Editing**: A sales rep has started editing a sent quote. The customer continues to see the previous version until an updated version is explicitly sent.
* **Editing Pending Approval**: The draft edits require approval before the updated version can be sent.
* **Signing Paused**: E-signing was voided (by the seller, by a signer reassignment, or by the provider). The customer cannot sign until the seller resumes or sends a fresh envelope.

A quote sitting in Draft with an approval request outstanding is shown as *Pending Approval* rather than plain Draft, so the queue state is always visible from the quote itself.

### Key Transition Rules

* A quote in **Draft** can be sent directly (without an approval step) if no approval rules are triggered. The approval check is re-evaluated at the moment of sending, so a quote that becomes approval-worthy after an edit is blocked from going out.
* A quote cannot be sent, sent as an update, or submitted for approval while any **Align to date** charge is missing its alignment date (see [Billing Configuration](#billing-configuration)). The refusal names each charge that needs a date.
* A quote that has never been sent cannot be sent while it contains a product, charge plan, or charge past its end of sales, unless the line is one the amended subscription already carries (see [End of Sales](#end-of-sales)).
* Editing a sent quote does not interrupt the customer-facing quote. The customer sees the last sent version until the updated version is explicitly published.
* Starting to edit a quote that has an active e-signing envelope automatically voids that envelope and sets the quote to *Signing Paused*.
* A quote in **Declined** or **Lost** can be reopened. Reopening always returns the quote to **Draft** for rework, clearing the decline, acceptance, e-signing, and approval state while preserving the record that it was previously sent.
* A quote cannot be reopened once its valid-until date has passed.
* A quote can be closed as lost from any state except Signed, Converted, Declined, Expired, or already Lost.
* Expiry is applied when the valid-until date has passed: the quote page stops offering acceptance, and the quote moves to *Expired* when a customer attempts to accept it.
* A quote that is Sent, Viewed, Awaiting Response, or Expired can have its validity extended. Once the customer holds the quote, its validity can only move forward: the new valid-until date must be in the future and later than the current one. A quote still in draft can be given any future valid-until date, earlier or later. Extending an *Expired* quote returns it to *Viewed*, or to *Sent* if the customer never opened it, and keeps its acceptance and e-signing state intact, unlike reopening. The extension is recorded in the quote's activity. The customer is not notified automatically, and extending validity does not renew an expired customer link; the seller resends the quote for that.

When a quote is blocked — by a missing alignment date, by a charge whose settings are not allowed, by a required field left empty, or by a quote rule — the quote shows a red strip naming the reason, both in CPQ and in CPQ inside HubSpot. **Send** is disabled with the reasons listed on it, and **Show issues** moves to the first problem. In the new-quote wizard, the Products step lists the charges to fix before the wizard can continue.

> **Note on reopening a sent quote:** While a reopened quote is being reworked, its customer link stays live but becomes read-only. The customer continues to see the last version that was sent to them and cannot accept, decline, or message until the seller sends the quote again. This prevents a customer accepting a version the seller has already withdrawn.

### Quote Types: New Business and Amendments

A quote has a **type** that determines how it converts into Younium:

* **Standard quote** — a quote for a brand-new subscription. This is the default.
* **Change quote** — a quote that amends an existing Younium subscription. It is linked to a source subscription and carries an **effective change date** that defines when the changes take effect in Younium. Change quotes are assigned their own number sequence (e.g. `CQ-2026-0001`) in addition to the standard quote number.

Change quotes are presented to sales users as **amendments**: the action that creates the Younium order is labelled *Amend Subscription*, and the quote builder shows which subscription is being amended.

An amendment requires an explicit **amendment type**:

| Amendment type     | Behaviour                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Change**         | Applied within the current term. The effective change date defaults to tomorrow, or to the earliest permitted date when tomorrow falls before it.                                                                                                                                                                                                                                      |
| **Renew & Change** | Renews the subscription at the end of its current term and applies the changes on the effective change date, in one step. The date defaults to the day after the current term ends and can be moved earlier, so a change that starts during the current term is sold together with the renewal on one quote. A next renewal term (in months) is required for the renewed subscription. |

Both amendment types take an effective change date from the later of the subscription's start date and the date of its last change, up to the day after its current term ends. An Evergreen subscription has no upper limit. CPQ refuses a date outside this range when the quote is created or edited, rather than at conversion, and names the earliest and latest permitted dates, and the date the subscription last changed when that is what sets the earliest date. A new amendment never opens on a date before the subscription's last change. A renewal on its own does not count as a change.

The effective change date can lie in the past, within that range. When it falls in a period that has already been invoiced, CPQ shows a note with the date the subscription is invoiced through: Younium credits the invoiced days at the old price and invoices them again at the new one on the next invoice. The note is informational and does not prevent the change.

A change quote starts from the subscription's charges that are in force on the effective change date. A charge that ends before that date, such as an earlier step of a ramped price, is not added to the quote and is left untouched in Younium on conversion; a charge that ends after the date is included. Changing the effective change date, or switching between **Change** and **Renew & Change**, re-aligns the quote: charges that have ended by the new date are removed, and charges in force again are restored. Products and charges the seller removed from the quote stay removed. The quote's figures for the subscription as it stands today are recalculated for the new date.

Each line of an amendment is marked with its own change — for example *Modified* or *Ending* — in the quote builder, on the customer quote page, and in the quote PDF. Where the subscription holds the same product, plan, and charge on more than one line, a change to one of those lines is shown on that line only.

### Subscription Terms on an Amendment

An amendment starts from the source subscription's terms, and the seller can change them as part of the amendment. The start date and currency are always fixed by the subscription being amended. What else can change depends on the amendment type:

| Term                            | Change                                                 | Renew & Change                             |
| ------------------------------- | ------------------------------------------------------ | ------------------------------------------ |
| **Subscription type**           | Editable (Termed or Evergreen)                         | Editable                                   |
| **Initial Term**                | Editable while the subscription has never been renewed | Fixed                                      |
| **Renewal Term**                | Editable                                               | Editable — sets the length of this renewal |
| **Auto Renewal**                | Editable                                               | Editable                                   |
| **Notice Period**               | Editable                                               | Editable                                   |
| **Start Date** and **Currency** | Fixed                                                  | Fixed                                      |

Changing the initial term moves the subscription's end date by the same number of months, counted from the subscription's current end date. Once a subscription has been renewed, Younium no longer accepts a change to its initial term, so CPQ locks the initial term on such a subscription. A Renew & Change amendment always renews the subscription first, so its initial term is locked too, and switching an amendment to Renew & Change restores the initial term and end date inherited from the subscription.

On conversion, the amendment carries to Younium every term that differs from the source subscription. An amendment that changes only the subscription's terms, with no change to its products, is a valid amendment and converts like any other.

On a Renew & Change amendment, the quote's figures for the renewal are calculated over the amendment's **Renewal Term**, which is the length Younium gives the renewal and the term the subscription keeps for later renewals. When the effective change date falls within the current term, the quote's TCV and the term end date shown on the quote and in its documents run from the effective change date to the end of the renewed term, which is the current term's end plus the **Renewal Term**.

Only one open change quote can exist per source subscription at a time. When a user picks a subscription to amend, the picker flags any subscription that already has an open change quote, along with which quote it is.

The lifecycle and workflow for change quotes follows the same state machine as standard quotes.

### Selecting a Subscription to Amend

When creating a quote, after selecting the customer the user is offered the option to base the quote on one of that customer's existing subscriptions instead of starting a new one. The picker lists the customer's subscriptions and their open-amendment state. Each subscription's summary counts the charges still in force on the default change date, tomorrow.

The amendment opens with the subscription's products and charges as they stand on the effective change date. A product or charge cancelled in Younium is left out once its cancellation has taken effect by that date, so it appears neither as a line on the quote nor in its totals or the figures held for the subscription as it stands today.

A subscription with a pending cancellation in Younium — one cancelled from a future date — cannot be amended in CPQ; creating a change quote on it is refused.

### Charges Already Cancelled in Younium

A charge set in Younium to end on a specific date is cancelled there, even though it is still billed until that date — typically after a restructure at renewal, where the old lines end with the term and new ones start the day after. When such a charge is still running on the effective change date, it comes onto the amendment with its own end date, including when that date is the subscription's end, and is listed in a separate **Already cancelled** section below the products, with its price and **Ends** followed by its end date.

A charge already cancelled in Younium is read-only and counts as it does in Younium:

| Figure                                                                         | Treatment                                                                     |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| **MRR** and **CARR**, on the quote and for the subscription as it stands today | Not counted, since a cancelled charge carries no recurring revenue            |
| **TCV**                                                                        | Counted from its start to its end date, matching the TCV of the Younium order |
| **Subtotal**, **Total**, and product totals                                    | Not counted                                                                   |

Its **Restore** menu brings the charge back into the quote's products:

| Option              | Effect                                                                                                                                                                          |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Follow contract** | The charge runs and renews with the subscription again, appears as modified, and counts toward recurring revenue. On conversion, Younium aligns the charge to the subscription. |
| **Specific date**   | Opens the date editor. Once a new end date is chosen, the charge appears as ending or modified and stays cancelled, on the new date.                                            |

A charge is listed under **Already cancelled** only while its end date matches the date it ends on in Younium. Once its end date is changed on the quote, it moves to the quote's products and stays there, and its date editor stays open while the change is saved.

Left untouched, the charge is not part of the amendment: nothing is sent for it on conversion, and it stays cancelled in Younium.

### Bundles on Amendments

When an amendment is created, CPQ rebuilds the bundles the subscription was sold with, so the seller amends a bundle rather than a set of loose lines. It recognises them from the **CPQ Bundle Code** each bundled charge carries in Younium (see [Integration Custom Fields](#integration-custom-fields)). A product on the subscription is grouped back into a bundle when every one of its charges carries the same code and that code belongs to an **Active** bundle offered in the quote's currency. A rebuilt bundle takes the shared quantity of its quantity-based products, or 1 where they differ.

| Situation on the subscription                                                                                                 | Result on the amendment                                                                                                                                 |
| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Every product of the bundle is present                                                                                        | The bundle is rebuilt, with its discount recalculated from the bundle's current configuration                                                           |
| An optional product of the bundle was not sold with the code                                                                  | The bundle is rebuilt without it, and that product stays an ordinary line                                                                               |
| A required product of the bundle was not sold with the code                                                                   | The bundle is not rebuilt: its lines stay ordinary lines and their discount carries over unchanged. Other bundles on the subscription are still rebuilt |
| The code matches no Active bundle, the bundle is not offered in the quote's currency, or one bundle product matches two lines | The lines stay ordinary lines                                                                                                                           |

A rebuilt bundle takes over the discount the subscription already has on its charges instead of adding a second one on top. CPQ uses a discount that covers exactly the bundle's charges first; failing that, one that covers more charges, narrowed to the bundle; and failing that, a discount covering fewer of them that runs with the order, widened to the bundle. A discount named after the bundle is preferred at each step. Where none fits, CPQ creates a new bundle discount. A discount dated to specific start and end dates on individual lines is never taken over. Removing a rebuilt bundle from the amendment gives that discount back to the subscription's remaining charges rather than deleting it.

Bundles added on an amendment carry their code to Younium on the new charges, so they are rebuilt on the next amendment in turn. A bundle without a **Code** is never rebuilt, because nothing on the subscription identifies it.

### Cloning a Quote

Any standard quote can be cloned to start a new quote from proven content. A clone carries the commercial substance of the original: products, bundles, charges, tier ladders, quantities, prices, charge-level and order-level discounts, ramp periods, currency, subscription terms, billing frequency, notes, and the assigned document template. It receives a fresh quote number, a fresh customer link, and validity dates recalculated from today.

A clone deliberately does not carry anything tied to the original deal or its history: the customer and bill-to account, contacts, CRM links, e-signing state, acceptance and send history, version history, approval state, and the link to any created subscription. The clone starts in the quote wizard with no customer selected, so the user chooses who it is for.

Change quotes cannot be cloned, and the customer on a quote can only be changed while it is still in Building or Draft and not being edited as a draft overlay. Swapping the customer clears the quote's contacts.

***

## 4. Products and Pricing

### Adding Products to a Quote

Products are browsed from the synced catalog, which leaves out any product flagged **Exclude from CPQ** in Younium (see [Younium Synchronisation](#21-younium-synchronisation)). Single-plan products are added whole; multi-plan products are added by selecting a charge plan, and all charges within the selected plan are added together. Each charge is added at its catalog price in the quote's currency. A charge that has catalog prices but none in that currency cannot be added, whether by a user or by the CPQ Agent. The product search shows a product without pricing in the quote's currency as unavailable to add.

### End of Sales

Younium's end-of-new-sales date on a product, charge plan, or charge decides what can be sold in CPQ. The date is the first day the item can no longer be sold: it remains sellable up to and including the day before, judged by calendar date in UTC. A date in the future takes effect on its day without waiting for a new sync.

A product is offered for sale only when the product itself, at least one of its charge plans, and at least one charge in that plan are all still sellable — the same rule Younium applies to availability for new sales. Products, plans, and charges past their end of sales are left out of the quote builder's catalog and search, bundles, and the CPQ Agent's product lookups, and CPQ refuses to add them to a quote.

An end of sales that is set but not yet reached is shown in the admin catalog: the product carries an orange **End of sales** status in place of *Active*, a charge plan shows an orange status dot with the date on hover, and a charge shows its **End of sales** date in its details.

| Situation                                                               | Behaviour                                                                                                                                                     |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A draft that has never been sent contains an item past its end of sales | The line shows a red **End of sales** marker and **Send to Customer** is disabled, naming the products to remove. Sending is refused, including from HubSpot. |
| Submitting such a draft for approval                                    | Not blocked; only sending is.                                                                                                                                 |
| A quote that has already been sent, or a resend                         | Not affected.                                                                                                                                                 |
| An amendment or renewal of a subscription that already carries the item | The existing line stays on the quote and can still be edited. Renewals are never blocked.                                                                     |
| Adding a new copy of an ended product to an amendment                   | Refused. A line counts as existing only when its charges match charges on the subscription being amended.                                                     |

> **Note on syncing end-of-sales dates:** CPQ reads the dates when products are synchronised from Younium. After an end-of-sales date is first set or changed in Younium, the product must be synchronised again before CPQ applies it.

### Product Bundles

Administrators maintain bundles under **Products → Bundles**, which lists each bundle with its code, number of products, currencies, and status. A bundle is made up of:

| Field                       | Description                                                                                                                                                 |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**                    | Required, up to 200 characters, and unique among the legal entity's bundles. Also used as the description of the bundle discount on a quote                 |
| **Code**                    | Optional, up to 50 characters, and unique. Written to Younium with every charge sold in the bundle, and needed for the bundle to be rebuilt on an amendment |
| **Currencies**              | The currencies the bundle is sold in. At least one is required                                                                                              |
| **Products in this bundle** | One charge plan per line, each plan at most once, with a **Qty**, a **Bundle** price per currency, and a **Required** flag                                  |
| **Bundle discount**         | How the bundle is discounted — see below                                                                                                                    |

Each line is one charge plan of a catalog product. A plan can join the bundle only if it is priced in every one of the bundle's currencies, and a currency can be added to the bundle only when every line is priced in it. All recurring products in a bundle share one price period, so a plan billed annually cannot join a monthly bundle. **Qty** applies to plans with a Quantity, Tiered, or Volume charge; other plans always count once.

A line's **Bundle** price replaces the catalog list price in that currency when the bundle is sold, and is set per charge — and per tier on Tiered and Volume charges. Where no bundle price is set, the list price applies. The editor's **Bundle price** card shows the list and bundle totals, the discount, and what the customer saves, in any of the bundle's currencies.

#### Bundle Statuses

| Status       | Meaning                                                                                                      |
| ------------ | ------------------------------------------------------------------------------------------------------------ |
| **Draft**    | Being prepared. Not offered to sellers                                                                       |
| **Active**   | Offered to sellers on quotes, and rebuilt on amendments. A bundle needs at least one product to be activated |
| **Inactive** | Withdrawn. Not offered to sellers, and not rebuilt on amendments                                             |

Changing a bundle does not reprice quotes it is already on: a quote keeps the products, prices, and discount the bundle had when it was added. Once a bundle is deactivated or deleted, the quotes that carry it keep it unchanged, but its products can no longer be edited there.

#### Bundle Discount

A bundle carries one of two kinds of discount, both percentages applied to every product included in the bundle:

| Discount                                  | Behaviour                                                                                                                                                                                                                                   |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Same discount on every product**        | One percentage, whichever products the customer keeps                                                                                                                                                                                       |
| **Discount grows with products included** | A ladder of tiers, each giving a percentage once a number of the bundle's products are included. The highest tier reached applies to all of them; below the first tier there is no discount. Each tier needs a different number of products |

Percentages run from 0 to 100. The discount counts products, not quantity: raising the bundle quantity does not move it up a tier.

#### Product Availability

A bundle product that has since changed in the catalog is flagged, both in the bundle editor and when a seller adds the bundle:

| Flag                                                                       | Cause                                                            |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **Excluded from CPQ in Younium**                                           | The product is active but hidden from CPQ                        |
| **No longer active in Younium**                                            | The product or its charge plan has been deactivated              |
| **No active charges in Younium**                                           | The charge plan has no active charges left                       |
| **No&#x20;*****currency*****&#x20;price for&#x20;*****charge***            | A charge has lost its price in one of the bundle's currencies    |
| **Now billed&#x20;*****period*****, but this bundle is&#x20;*****period*** | A recurring charge's price period no longer matches the bundle's |

A flagged optional product cannot be included on a quote. A bundle with a flagged required product cannot be added at all, and is shown to sellers as **A required product is unavailable**.

### Bundles on a Quote

With bundles available, the product catalog opened from **+ Product** lists the legal entity's Active bundles above the products. A bundle not sold in the quote's currency, or with no product that can be included, is shown but cannot be added. Adding a bundle opens a configuration step where the seller sets the **Bundle quantity** (from 1 to 9,999), unticks optional products the customer does not want, and sees the resulting bundle discount and price. Required products are always included.

On the quote, a bundle appears as one group with a **Bundle** badge, its quantity, and its list and net totals, with its products listed beneath it. The bundle quantity sets the quantity of every quantity-based product in the bundle; other products keep the quantity defined in the bundle. On Tiered and Volume charges the bundle quantity cannot exceed the highest finite tier.

Bundle products are locked: their quantity, price, charge discounts, and tier ladders cannot be changed one by one, and they cannot be removed individually. Changes go through the bundle itself, whose menu offers **Edit products** — to change the quantity or which optional products are included, recalculating the bundle discount — and **Remove bundle**, which removes its products and its discount together. A bundle must keep at least one product. Bundles can be changed while the quote is in Building or Draft, or while a sent quote is being edited, and they are carried through quote versions, restores, and clones.

### Product Rules

Product rules tell CPQ which products belong together. Administrators group them into **rule sets** under **Products → Rules**. Only administrators can open the page, and each legal entity has its own rule sets.

> **Note on availability:** Product rules are being introduced in stages, and the **Rules** page appears only where it has been switched on for the organisation. In this first stage, administrators build and maintain rule sets, but quotes are not yet checked against them: a rule set does not change what a sales user can add to a quote or send.

#### Rule Sets

The **Rules** page lists each rule set with its description, the number of rules it holds, when it was last updated, and its status, with the default listed first. The list can be searched. A rule set has:

| Field           | Description                                                                   |
| --------------- | ----------------------------------------------------------------------------- |
| **Name**        | Required, up to 200 characters, and unique among the legal entity's rule sets |
| **Description** | Optional, up to 1,000 characters                                              |
| **Rules**       | Up to 100 rules, in the order they are listed                                 |

The row menu offers **Edit**, **Activate** or **Deactivate**, **Set as default** or **Remove default**, and **Delete**.

| Status or action | Behaviour                                                                                                                                                |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Active**       | A new rule set starts active                                                                                                                             |
| **Inactive**     | Deactivating a rule set keeps its rules. Deactivating the default asks for confirmation and also removes it as the default                               |
| **Default**      | Marked with a ★. There is at most one default per legal entity, so setting a new default moves the star. Only an active rule set can be made the default |
| **Delete**       | Asks for confirmation and removes the rule set permanently                                                                                               |

If someone else saves a rule set, or changes its status or default, while it is open in the editor, the next save is refused and the editor offers to reload the latest version, so one administrator's changes never silently overwrite another's.

#### Building a Rule

Each rule is a card with a name and a one-line summary, such as *When Analytics is on the quote, requires Platform fee*. Cards can be collapsed, dragged into a new order, duplicated, and deleted. A rule has two parts:

* **When** — the conditions under which the rule applies, combined with **Match all** or **Match any**. Conditions can be grouped, up to three levels deep, to mix the two, with up to 20 conditions in a group and 50 in a rule. A rule with no conditions always applies.
* **Then** — one or more actions, up to 50 per rule.

A condition looks at one of the following:

| Condition                                                                                                                                                                                           | Comparisons                                  |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| **Product or bundle** — a product, optionally one of its plans (or **Any plan**), or a bundle                                                                                                       | **is on the quote**, **is not on the quote** |
| **Quote field** — for example **Initial term (months)**, **Renewal term (months)**, **Currency**, **Quote type**, **Billing frequency**, **Subscription type**, **Start date**, **TCV**, or **MRR** | Depends on the kind of field (see below)     |
| **Customer field** — for example **Country**, **VAT number**, or **Customer name**                                                                                                                  | Depends on the kind of field                 |
| **Quote custom field** and **Account custom field** — any active [custom field](#11-custom-fields) on quotes or accounts                                                                            | Depends on the kind of field                 |

| Kind of field                                               | Comparisons                                                                                       |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Number or amount                                            | **is at least**, **is more than**, **is exactly**, **is less than**, **is at most**, **is empty** |
| Date                                                        | **is before**, **is after**, **is empty**                                                         |
| Yes/no                                                      | **is**                                                                                            |
| A list of choices, such as currency, country, or a picklist | **is**, **is not**, **is one of**                                                                 |
| Text                                                        | **is**, **is not**, **contains**, **is empty**                                                    |

**is one of** takes up to 50 values, and a value can be up to 500 characters.

#### Rule Actions

An action is aimed at a product, optionally one of its plans, or at a bundle:

| Action       | Meaning                                                       |
| ------------ | ------------------------------------------------------------- |
| **Requires** | The target must be on the quote whenever the rule applies     |
| **Excludes** | The target must not be on the quote whenever the rule applies |

Each action has a severity, and an optional message to the sales user of up to 500 characters:

| Severity  | Intended effect                                     |
| --------- | --------------------------------------------------- |
| **Block** | Sending is blocked until the rule is met            |
| **Warn**  | The sales user is warned, and sending stays allowed |
| **Info**  | The sales user sees a note                          |

#### Checks When Saving

CPQ checks a rule set against the legal entity's catalog and settings when it is saved, and shows each problem on the rule it belongs to.

| Situation                                                                                                                             | Result                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| A product, plan, or bundle that does not exist, or a plan that does not belong to the chosen product                                  | Error. The rule set is not saved                                                           |
| A custom field that does not exist or is inactive, a field that cannot be used in rules, or a comparison that does not suit the field | Error. The rule set is not saved                                                           |
| A product or plan that is no longer sold in CPQ, or a bundle that is not active                                                       | Warning. The item is marked **Retired** in the editor, and the rule set can still be saved |
| The same product or bundle both required and excluded by rules in the set                                                             | Warning. The rule set can still be saved                                                   |

The same product and charge plan can appear on a quote more than once, and each occurrence is its own line, priced, edited, removed and converted to Younium independently. An amendment brings over every occurrence on the subscription, for example a product sold at one price in its first year and at another in its second.

### Charge Types

Each charge has a type that determines how it is billed and how it contributes to quote metrics:

| Type          | Description                              | Contributes to committed metrics                                                 |
| ------------- | ---------------------------------------- | -------------------------------------------------------------------------------- |
| **Recurring** | Billed at regular intervals              | Yes — the only type in MRR and CARR                                              |
| **One-Off**   | Billed once                              | Yes — in Subtotal, Total, and TCV                                                |
| **Usage**     | Billed based on consumption              | No — forecast only                                                               |
| **Measured**  | Measured consumption billing             | No — forecast only                                                               |
| **Credits**   | Sells a grant of prepaid Younium Credits | Yes — as a One-Off or Recurring charge, according to how the credits are granted |

Usage and Measured charges are **consumption charges**. They are billed on actual consumption in Younium, so they never contribute committed revenue on a quote. They can instead carry a forecast — see [Estimated Usage](#estimated-usage).

A Credits charge is billed as a One-Off charge when its credits are granted once, and as a Recurring charge when they are granted every billing period. It is counted that way in every total, in contract value, and in documents and the customer quote page — see [Credits Charges](#credits-charges).

### Charge Pricing Models

| Model        | Description                                                       |
| ------------ | ----------------------------------------------------------------- |
| **Flat**     | Fixed price regardless of quantity                                |
| **Quantity** | Price per unit multiplied by quantity                             |
| **Volume**   | All units priced at the tier rate for the total quantity          |
| **Tiered**   | Progressive pricing: each quantity band is priced at its own rate |
| **Rated**    | Usage-based pricing with tiers                                    |

### Price Period

The catalog price for a recurring charge is denominated in a price period (Monthly, Quarterly, or Annual). CPQ normalises all recurring charges to monthly when calculating MRR, so that MRR × 12 = CARR.

> **Note on price period vs billing period:** The price period says what the price *represents*; the billing period says how often the customer is *invoiced*. Changing the billing period changes invoicing cadence, not the run rate.

### Tier Ladders on Volume and Tiered Charges

Volume and Tiered charges are priced through a **tier ladder**. Each tier defines a quantity band with its own price:

| Field             | Meaning                                                                       |
| ----------------- | ----------------------------------------------------------------------------- |
| **From quantity** | Inclusive lower bound of the band                                             |
| **To quantity**   | Upper bound of the band. Left empty for an open-ended final tier, shown as ∞. |
| **Price**         | The price for the band                                                        |
| **Price base**    | Whether the band price is Flat or Per Unit                                    |
| **Discount**      | An optional per-tier discount percentage                                      |

The ladder is editable on the quote and is validated as a whole. CPQ enforces that the first tier starts at zero, that every tier except the last has an upper bound, that only the final tier may be open-ended, that an upper bound is never below its lower bound, and that the bands are contiguous with no gaps or overlaps. Editing per-tier prices requires the charge to allow price edits in the catalog; editing tier bounds and per-tier discounts does not.

A Volume or Tiered charge is discounted only through its per-tier discounts; it takes no percentage or fixed-amount discount on the line as a whole.

Quantity on a Volume or Tiered charge cannot exceed the ceiling of the highest finite tier. This limit does not apply to consumption charges, where the quantity is a forecast rather than a commitment.

An open-ended final tier is transmitted to Younium as an explicitly unbounded tier, so the platform prices it the same way CPQ does.

### Adjustable Fields per Charge

On a quote, each charge can have its quantity adjusted, including to zero or a negative value — negative quantities are used to model credits and removals within an amendment, and flow through to metrics and to Younium as entered. Unit price can be overridden only if **Allow price edit on quote** is switched on for that charge in the product catalog. Custom start and end dates can be set per charge, overriding the quote-level subscription dates. A custom end date can be no later than the end of the current term. A custom start date can be at most the day after the term ends when the subscription renews automatically, so a charge can be ended at the term end and re-added from the renewal date. Without auto-renewal, the start date can be no later than the term end. When a charge starts on the renewal date, its date editor shows the renewal term.

### Estimated Usage

Usage and Measured charges can carry a sales-entered forecast — **estimated usage** on a Usage charge, **estimated quantity** on a Measured charge. The forecast must be zero or greater, and zero is a meaningful value: it states explicitly that no consumption is expected.

A forecast does not create commitment. It is reported separately from committed revenue, on the quote, on the customer quote page, and in generated documents:

| Figure                              | Meaning                                                                                  |
| ----------------------------------- | ---------------------------------------------------------------------------------------- |
| **Estimated usage**                 | Forecast consumption revenue for the period, after any applicable discount               |
| **Usage discount**                  | The share of order-level discount falling on forecast consumption                        |
| **Estimated total including usage** | Committed period total plus forecast consumption                                         |
| **Estimated TCV**                   | Contract value plus forecast consumption across the term, shown as an approximate figure |

Consumption charges without a forecast contribute nothing and are presented to the customer as billed at invoicing. Forecasts are passed to Younium on conversion so the platform holds the same expectation.

### Credits Charges

A **Credits charge** sells a balance of Younium Credits: prepaid credits the customer draws down as they use the service. Credits charges are available where Credits is switched on for the organisation in CPQ and Credits is in use in Younium.

Each Credits charge belongs to a **credit type**, synchronised from Younium with the catalog. The credit type supplies the defaults for every charge that grants it: when credits expire, whether they roll over, the low-balance threshold, what happens when they run out, the overage and top-up prices in each currency, and the **rate card** — how many credits one unit of each usage type consumes. The admin catalog shows these defaults on the charge, under **Credits**.

The charge itself decides how the credits are granted, and its quantity is the number of credits, in whole numbers:

| Grant            | Billed as          | Quantity                            |
| ---------------- | ------------------ | ----------------------------------- |
| **Granted once** | A One-Off charge   | Credits granted at the start        |
| **Every period** | A Recurring charge | Credits granted each billing period |

#### Credit settings on a quote

A Credits charge added to a quote — in the quote builder, from a HubSpot deal, or through the API — is prefilled from its credit type in the quote's currency. Sales users can change the terms for that quote alone under **Credit settings** on the charge line, which also shows a one-line summary of the terms. Changes never alter the credit type itself.

| Setting                         | Description                                                                                                                                                                                                                       |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Expiry**                      | **End of term**, **After X months**, or **End of period**. Credits granted every period always expire at the end of each period; credits granted once expire at the end of the term or a number of months after they are granted. |
| **When credits run out**        | **Track only** notifies when the balance runs out, with no extra billing. **Bill overage** bills usage beyond the credits at the overage price.                                                                                   |
| **Low-balance threshold**       | The balance, in credits, at which the customer is considered to be running low                                                                                                                                                    |
| **Overage price**               | Price per credit used beyond the grant. Required when the charge bills overage.                                                                                                                                                   |
| **Top-up price**                | Price per credit for extra credits bought later                                                                                                                                                                                   |
| **Rollover at renewal**         | Unused credits carry into the renewal term                                                                                                                                                                                        |
| **Show free grants on invoice** | Zero-price grant lines are printed on invoices                                                                                                                                                                                    |
| **Rate card**                   | The usage types the credits can be spent on, and the credits one unit of each consumes. A usage type can be removed from the rate card for this quote.                                                                            |

All Credits charges of one credit type on a quote share one rate card, so a rate edited on one charge applies to each of them. A usage type can appear on the rate card of only one credit type per quote.

#### Rules checked before a quote goes out

CPQ checks a quote's Credits charges before it is submitted for approval, sent, published after an edit, or converted to a Younium order. While a rule is broken, the quote shows **Fix these credit settings to send** with each problem listed, and the action is refused.

| Rule                                | Detail                                                                                                                                                                                                 |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| One overage charge per credit type  | Only one charge of a credit type may bill overage, per ramp period. A second charge of the same credit type added to a new quote starts as **Track only**.                                             |
| Overage needs a price               | A charge that bills overage must have an overage price.                                                                                                                                                |
| Billing period of a recurring grant | Credits granted every period can be billed only Monthly, Quarterly, or Annually. A new charge is given an allowed billing period even when the quote-level billing frequency is set to something else. |
| Expiry on an Evergreen quote        | Credits cannot expire at the end of the term on an Evergreen subscription, since there is no term to end.                                                                                              |
| One credit type per usage type      | A usage type may appear on the rate card of only one credit type on the quote.                                                                                                                         |

#### Credits on an amendment

A change quote reads the credit settings of each Credits charge from the subscription in Younium, and changes to them are sent back on conversion. On a charge the subscription already has, **When credits run out** cannot change, the expiry of credits granted once cannot change, and a low-balance threshold or top-up price already set cannot be cleared.

Adding credits granted once, of a credit type the subscription already carries, makes the new charge a **top-up**: it takes the same terms as the existing charge and its terms cannot be edited. To give more credits on a charge that bills overage, the quantity of the existing charge is changed instead.

#### Credits in Younium

On conversion, each Credits charge reaches the Younium order with its credit settings and rate card. The overage price is sent only for a charge that bills overage.

> **Note on credit settings vs the credit type:** The credit type holds defaults. What the customer is sold is the terms on the quote, and those are the terms the Younium order carries.

### Billing Configuration

Each recurring charge carries billing settings that are inherited from the catalog unless explicitly overridden:

* **Billing period**: Monthly, Quarterly, Annual, End of Term, Biannual
* **Billing timing**: In Advance or In Arrears
* **Period alignment**: Controls what date billing periods align to (align to order, align to charge, align to month, align to calendar quarter, or align to a specific date)

When **quote-level billing frequency** is enabled, a single billing frequency is set on the quote and all charges inherit it by default.

**Alignment date.** A recurring or usage charge whose period alignment is **Align to date** needs a date to align its billing periods to. On a quote, each such charge new to the customer carries a required **Alignment date**, shown beneath the charge's dates (or beside the charge name on a ramped quote) and reading **Alignment date not set** until one is picked. On a ramped quote the date is set once per product line and shared by every period. One-off charges and charges the amended subscription already carries do not ask for one. The date is kept when a quote is cloned or revised, when a ramp period is copied forward, and on charges that come from a bundle.

On conversion, the alignment date is sent to Younium with the charge, and the quote's contract value is calculated with the same date. A quote accepted before alignment dates were collected converts with its charges aligned to the quote's start date.

### Ramp Periods

A **ramp-up** prices a contract that changes over its term — 25 users in the first year and 40 in the second, or a price that steps up once an introductory year ends. It divides the quote's initial term into consecutive **periods**, and each period holds its own charge lines, each with its own quantity, unit price, charge-level discount, tier ladder, and usage forecast. A product can be added to a single period or left out of one, so each period states exactly what the customer has during it.

Ramp-up is available where it is switched on for the organisation. Switching it off stops new ramps being created; quotes that are already ramped keep their periods and continue to price, display, and convert as ramped quotes.

A quote can be ramped while it is in Building or Draft, or while a sent quote is being edited as a draft overlay. It must be a Termed subscription with an initial term and a subscription start date. Change quotes, Evergreen quotes, and sales orders cannot be ramped. A ramp is created with **Create ramp-up**, either in the new-quote wizard's Products step or later on the quote, and a ramp built in the wizard carries onto the quote unchanged.

The rhythm chosen for the ramp decides how the term is divided:

| Rhythm        | Period length                  | Periods named           |
| ------------- | ------------------------------ | ----------------------- |
| **Annual**    | 12 months                      | Year 1, Year 2, …       |
| **Biannual**  | 6 months                       | Half 1, Half 2, …       |
| **Quarterly** | 3 months                       | Quarter 1, Quarter 2, … |
| **Monthly**   | 1 month                        | Month 1, Month 2, …     |
| **Custom**    | Set for each period, in months | Period 1, Period 2, …   |

Periods run back to back from the subscription start date, with no gaps or overlaps. When the term is not a whole multiple of the rhythm, the final period is shorter and is named *Period N*, so a short tail is never labelled as a full year or quarter. Custom periods must add up exactly to the initial term. Any period can be given its own name, of up to 100 characters.

**What goes into the later periods?** decides how the later periods start when a ramp is created:

| Option                         | Behaviour                                                                                                                                                                                                 |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Carry the products forward** | Every later period starts with a copy of the first period's recurring and consumption charges, at the same quantities and prices. One-off charges stay in the first period, so they are not billed again. |
| **Fill the first period only** | Later periods start empty.                                                                                                                                                                                |

The period sets the dates of every charge in it, and a charge added to a ramped quote is added to one period and takes that period's dates. **Copy forward** pushes a period's quantities, prices, charge-level discounts, tier ladders, and forecasts into the next period, either for the whole period or for a single line, and adds back any line the next period had dropped. It changes only the next period, and one-off charges are never copied. Below the charge lines, **How the contract grows** shows each period's value and run-rate, how the run-rate changes from the period before, and an *After renewal* projection of the contract once it renews. The projection is shown to the seller only and never reaches the customer.

A ramp follows later changes to the quote:

| Change                                     | Effect on the periods                                                                                                                                                                                             |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Edit ramp-up**                           | Divides the term again with the chosen rhythm. The first period's lines are kept, and the later periods are rebuilt from them according to **What goes into the later periods?**                                  |
| **Remove ramp-up**                         | Returns the quote to one price for the whole term, keeping the first period's pricing. When the quote has discounts that run for only part of the term, CPQ asks first and deletes those discounts with the ramp. |
| Start date changed                         | The periods move with the new start date and keep their lines, prices, and names.                                                                                                                                 |
| Initial term shortened                     | Periods the shorter term no longer reaches are dropped with their lines. The periods that remain keep their lines, prices, and names.                                                                             |
| Initial term lengthened                    | Periods are added to cover the new months and start empty. A Custom ramp keeps the lengths already set and adds the remaining months as one new period.                                                           |
| Switched to Evergreen, or to a sales order | The ramp is removed, since there is no term to divide. Discounts that run for only part of the term are deleted with it, after the same confirmation as **Remove ramp-up**.                                       |

A charge whose dates follow a milestone cannot keep that link once the quote is ramped. Creating the ramp asks first, then releases the charge from the milestone, and the charge takes the dates of its period.

How discounts interact with periods is described in [Discounts on Ramped Quotes](#discounts-on-ramped-quotes), how a ramp affects the quote's figures in [Quote Metrics](#6-quote-metrics), and how a ramped quote arrives in Younium in [Ramped Quotes on the Younium Order](#ramped-quotes-on-the-younium-order).

### Settings

The first two are configured under **Settings → Quote Settings**; the third is set per charge in the product catalog.

| Setting                                  | Description                                                                 | Default |
| ---------------------------------------- | --------------------------------------------------------------------------- | ------- |
| **Enable Quote-Level Billing Frequency** | Quotes carry a single billing frequency that all charges inherit by default | On      |
| **Default Billing Frequency**            | Billing frequency pre-selected on new quotes                                | Monthly |
| **Allow price edit on quote**            | Lets sales users change this charge's unit price on a quote                 | Off     |

***

## 5. Discounts

CPQ supports discounts at two levels, which compose: a discount on an individual charge, and a discount across the order.

### Charge-Level Discounts

An individual charge can carry either a percentage or a fixed-amount discount. It is applied to that charge before any order-level discount. A fixed-amount discount cannot exceed the charge's own amount, so a charge total never falls below zero. Because it is applied at the line, it is already reflected in the quote subtotal.

A fixed-amount discount is one amount off the whole line, not an amount off each unit: €300 off 10 units at €500 brings the line from €5,000 to €4,700. On a Flat charge, which is priced regardless of quantity, the amount comes off the charge once.

Which kind of discount a charge accepts depends on how it is priced:

| Charge                                                 | Charge-level discount                                                                                                                                                                        |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Recurring** and **One-Off**, Flat or Quantity priced | A percentage from 0% to 100%, or a fixed amount no greater than the line's price                                                                                                             |
| **Usage** and **Measured**                             | A percentage only. The fixed-amount option is not offered on these lines, and CPQ refuses one                                                                                                |
| **Volume** and **Tiered**                              | A discount per tier band only — see [Tier Ladders on Volume and Tiered Charges](#tier-ladders-on-volume-and-tiered-charges). CPQ refuses a percentage or fixed amount on the line as a whole |

The same rules apply whichever way the charge is added: in the quote editor, by the [CPQ Agent](#18-cpq-agent-ai-assistant), or from a deal imported into a new quote, where a discount suggested for a Volume or Tiered charge is left out.

On an [amendment](#quote-types-new-business-and-amendments), adding or changing a charge-level discount on a charge carried over from the subscription — percentage or fixed amount — marks the charge as modified and changes its price in Younium on conversion. On a Renew & Change amendment, the discount counts in the quote's TCV just as it does on a new-business quote. A revised quote's change summary lists a changed fixed-amount discount as well as a changed percentage.

### Order-Level Discounts

An order-level discount applies across charges and is presented to the customer as a discount on the deal.

| Property        | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| **Description** | Free-text label shown to the customer                            |
| **Type**        | Percentage or Fixed Amount                                       |
| **Value**       | The percentage or amount                                         |
| **Duration**    | How long the discount runs — required                            |
| **Apply to**    | All charges, or specific selected charges                        |
| **Sort order**  | Controls application sequence when multiple discounts are active |

A fixed-amount order discount is distributed across the charges it applies to in proportion to their share of the subtotal, so recurring, one-off, and forecast consumption each absorb their part.

A discount on specific charges applies to the quote lines it was given, not to every line of the same catalog charge. When the same product appears twice — inside a bundle and on its own, for example — a discount on one of them leaves the other untouched, both in the quote's contract value and in Younium. A discount on specific charges whose lines have all been removed from the quote is left out when the quote is converted.

### Bundle Discounts

Adding a [product bundle](#product-bundles) adds its bundle discount to the quote as an order-level discount: a percentage, described with the bundle's name, applying to the bundle's products and running for the whole contract. It is listed among the order discounts with a **Bundle** badge, applying to **Products in this bundle**, together with the amount it takes off the recurring and one-off totals.

The bundle discount follows the bundle. It is recalculated whenever the bundle's products change — on a bundle whose discount grows with the products included, unticking a product can lower the percentage — and it is removed with the bundle. It cannot be edited or deleted on its own. Bundle prices are applied first, and the bundle discount is taken off the bundle prices.

### Discount Duration

Every order-level discount must state an explicit duration. This prevents an open-ended discount being created by accident and makes the revenue impact unambiguous:

| Duration                      | Behaviour                                                                                                     |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **1, 3, 6, 12, or 24 months** | Runs from the subscription start for the chosen number of months. Available when it is shorter than the term. |
| **Until next renewal**        | Runs to the end of the current subscription term.                                                             |
| **Whole contract**            | Runs for the full subscription term.                                                                          |
| **Custom**                    | Explicit start and end dates. The end date is required; the start defaults to the subscription start.         |

On a *Renew & Change* amendment, the subscription term in these durations is the renewed term: *Until next renewal* and *Whole contract* run to the end of the next renewal term, and custom dates can run up to that date.

Custom dates snap to billing period boundaries. Choosing a specific discount start date on a quote that has no subscription start date yet pre-fills the subscription start to match.

Any discount other than *Whole contract* is **time-limited**, because it is bound to specific dates rather than the subscription's own term.

**Impact on metrics**: Time-limited discounts are excluded from MRR and CARR, which reflect steady-state recurring revenue. They are included in TCV, which is calculated period by period across the full subscription term. A discount dated to end exactly at the term end is still treated as time-limited.

When a discount is created or edited, CPQ prices it server-side and shows the resulting impact on contract value and run rate before it is saved, so the effect is visible at the point of decision.

### Discounts on Ramped Quotes

On a [ramped quote](#ramp-periods), an order-level discount can be added to a single period. Its duration is then offered relative to that period:

| Duration                      | Behaviour                                                                                                                      |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| ***Period*****&#x20;only**    | Runs from the start to the end of that period — for example *Year 2 only*.                                                     |
| ***Period*****&#x20;onwards** | Runs from the start of that period to the end of the contract — for example *Year 2 onwards*. Not offered on the final period. |
| **1, 3, 6, 12, or 24 months** | Counted from the start of that period rather than from the subscription start, and never beyond the end of the term.           |

**Until next renewal**, **Whole contract**, and custom dates remain available. Where two options describe the same stretch, such as *Year 1 only* and *12 months* on an annual ramp, only one is offered. A discount on specific charges added to a period lists that period's charges, and applies to the same lines in every period its dates reach.

Adding an order-level discount that covers only part of the term to a quote that is not yet ramped ramps it automatically, as long as the quote can be ramped. The term is divided into the undiscounted stretch before the discount, if there is one, the discounted stretch, and whatever follows, with the products carried forward into each period, so the discounted stretch is priced on its own. The discount form states the periods the quote will be divided into before the discount is saved. A discount that covers the whole term leaves the quote unramped.

Editing such a discount reshapes the periods to its new dates, or removes them when the discount now runs for the whole contract. The periods are left as they are when a later period carries pricing of its own or another dated discount shapes them, and the discount form states which of these will happen before the change is saved.

### Discounts on an Amendment

On a [change quote](#quote-types-new-business-and-amendments), an order-level discount never reaches back into the part of the subscription that has already been delivered. Where a discount has no start date of its own, CPQ takes its start from where it came from:

| Discount                                       | Starts on                                                                                                                                                                                                                                         |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Added in the amendment                         | The effective change date, whichever duration is chosen                                                                                                                                                                                           |
| Carried over from the subscription             | The start date it has on the subscription in Younium, including when the seller picks a new duration for it such as **Until next renewal** or **Whole contract**. A carried discount that already ran from the subscription start keeps doing so. |
| Given its own start date with **Custom** dates | That date                                                                                                                                                                                                                                         |

The same start applies to the amendment's TCV and its change from the subscription as it stands today, to the discount dates shown in generated documents, and to the discount on the Younium order the amendment creates or updates.

### Discount Visibility

Order-level discounts are shown to the customer on the hosted quote page, with their description, type, value, applicable date range, and what they apply to. When a discount applies to specific charges, those charges are named, each once, even on a ramped quote where the same charge appears in several periods. Discount data is also available to PDF templates, so template authors can render a discount breakdown in custom documents. On conversion, each order discount is created in Younium with its description, so a later amendment of the subscription shows the same description.

An approval workflow can also add order-level discounts of its own, which sales users cannot change — see [Discounts from a Workflow](#discounts-from-a-workflow).

***

## 6. Quote Metrics

CPQ calculates the following figures on every quote, updated as products and discounts change:

| Metric                      | Definition                                                                                                                                                                                                                                                                                                             |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Subtotal**                | Recurring charges per the period chosen in **Display totals in**, before order-level discounts. One-off and consumption charges are excluded.                                                                                                                                                                          |
| **Total**                   | Recurring charges per the period chosen in **Display totals in**, after charge-level discounts and order-level discounts that run for the whole contract. Time-limited discounts, one-off charges, and consumption charges are excluded. On a sales order, which has no recurring charges, Total is the one-off total. |
| **One-Time Total**          | One-off charges after applicable discounts                                                                                                                                                                                                                                                                             |
| **Total Discount**          | The difference between Subtotal and Total — the per-period impact of order-level discounts that run for the whole contract                                                                                                                                                                                             |
| **MRR**                     | Monthly Recurring Revenue: recurring charges normalised to monthly, less discounts that run for the whole contract                                                                                                                                                                                                     |
| **CARR**                    | Contracted Annual Recurring Revenue: MRR × 12                                                                                                                                                                                                                                                                          |
| **TCV**                     | Total Contract Value: full-term revenue, calculated period by period so time-limited discounts are reflected                                                                                                                                                                                                           |
| **TCV before discount**     | Contract value with order-level discounts excluded, used to show the customer the total discount on a termed quote                                                                                                                                                                                                     |
| **Estimated usage figures** | Forecast consumption revenue, reported separately — see [Estimated Usage](#estimated-usage)                                                                                                                                                                                                                            |

The **Next billing cycle** summary shows what the first invoice amounts to: one billing period of recurring charges, one-off charges, and usage billed at invoicing. A time-limited order-level discount reduces the recurring part only for the months of that billing period it covers, and reduces one-off charges only when it is in force on the first invoice date.

On an amendment, CPQ also holds the equivalent figures for the subscription as it stands today, so the change in run rate and contract value can be reported rather than only the new absolute values.

On an amendment, TCV also counts the recurring revenue of subscription charges that the quote carries no lines for: charges replaced by an earlier change to the subscription, and charges that ended before the effective change date. This keeps the quote's TCV in line with the TCV of the Younium order. Total, MRR and CARR are unaffected, since those charges no longer contribute to the run rate. A charge already cancelled in Younium that is still running on the effective change date counts toward TCV up to its end date but not toward Total, MRR or CARR — see [Charges Already Cancelled in Younium](#charges-already-cancelled-in-younium).

On a *Renew & Change* amendment, TCV runs to the end of the renewed term, so it covers the current term and the next renewal term, as Younium does for the renewed order. A plain *Change* amendment keeps the subscription's current term end.

A product or charge added on an amendment that has no start date of its own and follows the contract is counted in TCV from the effective change date, not from the subscription's original start. On a **Renew & Change** quote, for example, a line added for the renewal term contributes that term's value only, and a discount on it reduces TCV only for the time the line runs. Lines carried over from the subscription and cancelled lines continue to be counted across the whole order.

A subscription charge carried onto an amendment whose billed amount changes — through its quantity, unit price, tier ladder, or a newly added discount — takes the new amount from the effective change date, as it does in Younium. TCV counts the charge at its previous amount until the day before the change date and at its new amount from then on, so the change in contract value reflects only the remaining months. On **Renew & Change**, where the change date is the day after the current term ends, the charge keeps its previous amount for the rest of the current term. A charge on a ramped quote follows its period instead.

On a quote that is not ramped, a recurring line with a later start date of its own, set directly or by a milestone's planned date, is billed only from that date. Until then it is left out of Subtotal and Total, which read the start of the quote; the totals show the line in a separate dated row from the date it starts, rather than as if it ran from the start of the quote.

On a [ramped quote](#ramp-periods), each figure follows the periods:

| Metric                      | On a ramped quote                                                                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Subtotal** and **Total**  | The first period's recurring charges, per the **Display totals in** period                                                                       |
| **MRR** and **CARR**        | The rate of the final period — the rate the contract ends on and would carry into a renewal — less discounts that run to the end of the contract |
| **TCV**                     | The sum of every period's value, each over its own length and after the discounts in force during it                                             |
| **Estimated usage figures** | Forecast consumption summed across the periods, each at its own forecast                                                                         |

A discount that covers only part of a period reduces that period in proportion to the time it covers, counted the same way as TCV: a whole month counts as one, and a partial month is prorated by its days. The periods' values therefore add up to TCV. A discount chosen as *Period onwards* runs to the end of the contract and lowers MRR and CARR; one limited to a single earlier period does not.

> **Note on CARR and TCV on a ramped quote:** On a ramped quote, CARR multiplied by the term in years does not give TCV, because CARR reads the final period while TCV counts every period. A ramp that steps up reports a CARR above the average of its periods; the difference is the earlier, lower-priced periods, not an error.

> **Note on Evergreen quotes:** An Evergreen subscription has no fixed term, so recurring TCV is not meaningful and is reported as zero. MRR and CARR are still calculated.

### Quote Value

Wherever a quote is summarised as a single figure — the convert and sign dialogs, the version history on the customer quote page and in the quote's activity, search results, the dashboard, the quote picker used to test an approval workflow, the HubSpot deal cards and notes, Slack, and the CPQ Agent — CPQ shows the same value, chosen by the kind of quote:

| Quote                | Value shown                                                                  |
| -------------------- | ---------------------------------------------------------------------------- |
| **Fixed-term quote** | Total contract value                                                         |
| **Evergreen quote**  | Total per the **Display totals in** period, with the one-off total beside it |
| **Sales order**      | The one-off total                                                            |

Where quotes are added together or averaged, such as the value of all quotes on a deal, CPQ uses TCV.

When an Evergreen quote is converted, the convert dialog shows its term as *Evergreen* and, where time-limited discounts apply, a breakdown of the total per period in each discounted and undiscounted stretch. The version history values each version from the snapshot taken when it was sent.

***

## 7. Approvals

The approval workflow is optional and switched on per legal entity with **Enable Approval Workflow**. When enabled, CPQ evaluates every attempt to send a quote — and every attempt to publish a draft update of a sent quote — and requires approval when the quote breaches the configured rules. The check is enforced when the quote is sent, not only when it is submitted, so a quote cannot be edited past the rules after approval.

### Approvers

Approvers are the members of an **approval group**. Each legal entity has a default group, and additional groups can be defined to route different situations to different people.

Any active member of an assigned group can approve — the request is not held for one named individual, and there is no quorum. Approving on behalf of the group completes that group's step.

### Deciding Whether Approval Is Required

CPQ offers two ways to make that decision, chosen with **Decide With a Workflow**.

**Discount threshold.** By default, a quote requires approval when its total effective discount percentage exceeds the configured maximum. The percentage is the share of contract value that discounts remove: the difference between TCV before discount and TCV, divided by TCV before discount. It combines order-level and charge-level discounts, and because TCV is calculated period by period, a time-limited discount counts only for the months it runs. An Evergreen quote, which has no fixed term, is valued over 12 months for this purpose — on an amendment, the 12 months following the effective change date — and a sales order over its one-off charges. The threshold is a ceiling rather than a limit: a quote discounted to exactly the configured maximum passes without approval. When approval is triggered, the reason is recorded on the request in plain language, naming the discount and the threshold it exceeded. When the changes to a quote that is already with the customer are approved, that approval covers the updated version for as long as its discount stays at or below the discount it was approved at; raising the discount further requires approval again. An approval given before the quote was last sent does not carry over to a new round of changes.

**Approval workflow.** A legal entity can instead decide approval with a visual **workflow** — a diagram of the organisation's own rules, replacing the discount threshold entirely while it is active.

### Approval Workflows

A workflow is drawn as a graph, one per legal entity, and is evaluated against a quote whenever the approval decision is made. It is built from these nodes:

| Node                   | Purpose                                                                                    |
| ---------------------- | ------------------------------------------------------------------------------------------ |
| **Start**              | Entry point. Supplies facts about the customer and the quote owner.                        |
| **Customer condition** | Branches on customer attributes                                                            |
| **Quote condition**    | Branches on quote values                                                                   |
| **Quote**              | Applies rules to the quote's own fields, and supplies quote figures as facts               |
| **Approval**           | Marks approval as required, optionally assigning a specific approval group                 |
| **Add discount**       | Adds a locked order-level discount to the quote                                            |
| **Apply product rule** | Chooses a product rule set to check the quote against, alongside or instead of the default |
| **Finish**             | End point                                                                                  |

Conditions compare a fact against a value using equality, before/after for dates, and the numeric comparisons greater than, greater than or equal, less than, and less than or equal. Several conditions can be combined on one node with AND and OR.

For payment term, country, and picklist and Yes/No custom fields, the value is chosen from a list of the values a quote can hold, including an empty entry for a quote with no value. Number and date custom fields take a number or a date and offer the comparisons that suit their type. A workflow cannot be saved while one of its conditions names a value that is no longer available.

The facts available to conditions are:

| Group             | Facts                                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Customer**      | Whether the customer is new or existing, VAT validation status, country, payment term, and account custom fields |
| **Quote owner**   | Name, email, and whether the owner is a standard user or an administrator                                        |
| **Quote value**   | Discount percentage, discount amount, TCV, CARR, one-time total                                                  |
| **Subscription**  | Subscription type, initial term, renewal term, auto-renewal, notice period, billing frequency                    |
| **Products**      | Whether any line carries a price override                                                                        |
| **Custom fields** | Quote custom field values                                                                                        |

### Quote Rules from a Workflow

The Quote node can also constrain what a sales user is allowed to put on the quote, rather than only deciding approval. Each of the quote's subscription type, initial term, renewal term, auto-renewal, notice period, billing frequency, and currency can be:

| Rule                  | Effect                                                                 |
| --------------------- | ---------------------------------------------------------------------- |
| **Locked**            | The field cannot be changed                                            |
| **Forced value**      | The field is set to a required value                                   |
| **Allowed values**    | The field is restricted to a defined set of options                    |
| **Requires approval** | The field may be set freely, but doing so sends the quote for approval |

When a rule sends a quote for approval, the approval request states each rule the quote broke in plain words — for example *Order discount duration is Whole contract* — alongside the route the workflow took.

### Order Discount Duration Rules

The Quote node can also govern the [duration](#discount-duration) of order-level discounts. **Order discount duration** takes a set of durations — 1, 3, 6, 12, or 24 months, Until next renewal, Whole contract, Custom dates, Ramp period only, and Ramp period onwards — and supports only two of the rules above:

| Rule                  | Effect on order-level discounts                                                                                                     |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Allowed values**    | Only the chosen durations are offered when a sales user adds a discount, and CPQ refuses to save a discount with any other duration |
| **Requires approval** | A discount with one of the chosen durations may be added, but sends the quote for approval                                          |

A discount's duration is read from its dates, so a discount whose dates match more than one duration — 12 months on a 12-month term is also *Until next renewal* — is allowed when any of those durations is allowed. CPQ also refuses an edit that moves a discount's dates to a duration the rule does not allow, and refuses reactivating such a discount.

A discount added by a sales user that the rule does not allow — for example one added before the rule came into force — is never removed automatically. Instead, the quote cannot be sent, submitted for approval, resent, or sent as an updated version until the discount is changed or removed, and CPQ names each such discount and its duration.

Under **Allowed values**, only discounts a sales user adds are checked. Discounts that a [change quote](#quote-types-new-business-and-amendments) carries over from the subscription can still be kept, but under **Requires approval** they count like any other discount, so a carried discount with a flagged duration sends the amendment for approval. Discounts added by a product bundle or automatically by a workflow are not checked, and a quote created by cloning, by a new revision, or by restoring a sent version keeps its discounts as they are.

### Discounts from a Workflow

An **Add discount** node adds a percentage order-level discount to every quote whose path through the workflow reaches it. Each node reached adds one discount, described by the node's name, or as *Workflow discount* when the node keeps its default name.

| Setting                   | Description                                                                                                                                                                                                                                                                                      | Default        |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
| **How much?**             | The discount percentage, above 0% and at most 100%                                                                                                                                                                                                                                               | 10%            |
| **How long does it run?** | 3, 6, 12, or 24 months, **Until next renewal**, or **Whole contract**, with the same meaning as for a [manual discount](#discount-duration). A fixed number of months never runs past the end of the term, and on a quote with no fixed term **Until next renewal** runs for the whole contract. | Whole contract |
| **Which charges?**        | One-off, Recurring, Usage, and Measured. When none are picked, the discount applies to every charge; otherwise only to charges of the picked types. A quote with no charge of a picked type gets no discount.                                                                                    | None picked    |

Workflow discounts apply to new-business quotes and sales orders while they are in *Building* or *Draft*, and to a draft update of a sent quote. They are not added to amendments. They apply only while both **Enable Approval Workflow** and **Decide With a Workflow** are on.

CPQ runs the workflow again, and adds, updates, or removes the quote's workflow discounts to match, whenever the quote's subscription terms, products, charges, bundles, or ramp periods change. Saving the workflow, or switching either setting above, does the same for every open quote in the legal entity, so connecting an **Add discount** node with no condition in front of it discounts every eligible open quote. A quote that no longer reaches a node loses that node's discount.

A sales user cannot edit or remove a workflow discount; it is marked *Workflow* on the quote and changes only when the quote does. In every other respect it is an ordinary order-level discount: it is included in the quote's totals and TCV, shown on the customer quote page and in documents, and carried into the Younium order on conversion. Clones, revisions, and restored versions keep it.

> **Note on workflow discounts and approval:** A workflow discount does not count towards the discount percentage used to decide approval — neither the discount threshold nor the discount percentage fact. The TCV and CARR facts do include it, so a condition on either of those figures placed in front of an **Add discount** node can be switched off by the very discount it adds.

### Product Rules from a Workflow

An **Apply product rule** node lets the workflow choose which [product rule](#product-rules) sets a quote is checked against, so that different customers, owners, or kinds of quote can follow different rules. Without such a node, every quote is checked against the legal entity's default rule set.

| Setting                | Description                                                                                                                                                                     | Default |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| **Rule set**           | The rule set the node applies. Only active rule sets can be picked, with the default marked ★, and **Open Rules** opens the rule set in a new tab                               | None    |
| **How does it apply?** | **Amend** adds the rule set to the default, and the quote is checked against both. **Override** replaces the default, and the quote is checked against the node's rule set only | Amend   |

The canvas shows each node's rule set and whether it amends or overrides. A node with no rule set is an error that stops the workflow being saved. A node whose rule set has since been deactivated or deleted is a warning: the workflow can be saved, but the node adds nothing.

CPQ runs the workflow each time it checks a quote's rules and each time a quote is sent or submitted, and applies the rule sets of every **Apply product rule** node the quote's path reaches. The default rule set is checked first, then each node's rule set in the order the path reaches it, so where an added rule set requires a product that the default excludes, or the other way round, the added rule set wins. When any reached node overrides, the default is left out; several nodes' rule sets still all apply, and a rule set reached twice is checked once. Nothing is written to the quote, so a quote whose path changes follows the new rule sets from its next check.

Rule sets from a workflow apply only while both **Enable Approval Workflow** and **Decide With a Workflow** are on. Otherwise, and whenever the workflow cannot be evaluated, quotes are checked against the default rule set alone.

> **Note on an inactive override:** An **Override** node removes the default even when its own rule set has been deactivated or deleted. If no other node the quote reaches adds a rule set, the quote is checked against no rules at all.

A test run of the workflow describes what each **Apply product rule** node would do — for example *Would check the quote against "Seat-based licensing" as well as the default rule set* — and ends by naming every rule set the quote would be checked against. It warns when workflow approvals are switched off, because the nodes then have no effect.

### Chained and Parallel Approval

An Approval node can name a specific approval group. When a workflow contains several Approval nodes, CPQ opens every approval that is ready at the same time in parallel, and opens downstream approvals only once the approvals before them are satisfied. This produces a sequential chain where the diagram is sequential, and simultaneous sign-off where it is not. An Approval node with no group named falls to the default approvers.

Before it is saved, a workflow is validated as a diagram: it must have an entry point, every branch must have a default path, conditions may only reference facts that are actually available at that point, and unreachable nodes are reported. A workflow can be run against a real quote in the editor and replayed step by step on the canvas to confirm it behaves as intended before it goes live.

> **Note on an incomplete workflow:** If workflow mode is on and the workflow cannot be evaluated, CPQ requires approval rather than letting the quote through. If no workflow has been drawn at all, no approval is required. Quote field rules behave the opposite way: when they cannot be evaluated, no restrictions are applied, so a broken diagram never blocks a sales user from working.

### Approval States

An approval request is tracked separately from the quote's own status:

| Approval state   | Meaning                                                                                    |
| ---------------- | ------------------------------------------------------------------------------------------ |
| **Not required** | No approval is outstanding                                                                 |
| **Pending**      | Awaiting a decision                                                                        |
| **Approved**     | Cleared to send                                                                            |
| **Rejected**     | Sent back for revision                                                                     |
| **Cancelled**    | Superseded, for example when another approver rejected the quote or the quote was reopened |

Submitting a draft quote for approval moves it to *Pending Approval*. A quote that the rules do not send for approval cannot be submitted: CPQ refuses with the reason — *This quote does not need approval, so it can be sent to the customer as it is.* — and the quote stays in Draft, ready to be sent directly. The same check applies to every way of submitting a quote. Submitting a draft update of a quote that is already with the customer does not change what the customer sees — the quote stays *Sent* or *Viewed* while approval runs in the background.

Rejecting requires a reason, which is recorded and sent to the requester, and returns the quote to Draft for rework. Resubmitting after a rejection creates a new request and leaves the first attempt on record, so the approval history of a quote is complete.

### Notifications

Approvers are notified when a quote is submitted, and the requester is notified when a decision is made. Where Slack is connected, the request and the decision are also posted to the quote's thread in the team channel, and approvers whose Slack account is linked receive the request as a direct message and can approve or reject without leaving Slack — see [Slack](#15-slack).

### Settings

Configured under **Settings → Approval Workflow**, where the approval groups are also maintained.

| Setting                               | Description                                                           | Default |
| ------------------------------------- | --------------------------------------------------------------------- | ------- |
| **Enable Approval Workflow**          | Activates approvals                                                   | Off     |
| **Decide With a Workflow**            | Uses the visual workflow instead of the discount threshold            | Off     |
| **Maximum Discount Without Approval** | The discount percentage a quote may reach before approval is required | 20%     |

The approval emails — to approvers on submission, and to the requester on a decision — are sent as standard, with no on/off switch in the settings screens.

***

## 8. Quote Versioning

CPQ tracks versions of a quote. A version snapshot is created each time the quote is sent — on first send, on resend, and when an updated version is published from a draft edit — capturing the quote as the customer received it.

Each version records what changed relative to the previous one, covering added, modified, removed and ending charges, tier changes, credit settings changes, discount changes, and changes to validity, subscription terms, currency, bill-to details, notes, and the assigned document template. On an amendment, the quote is also compared against the subscription as it stands today.

Versions carry a natural-language summary of the change (for example "Added Analytics Add-on, reduced Enterprise License quantity from 50 to 40, increasing total by 5%"). The summary names each product line with its plan, such as "Reporting (Pro)". A product removed and added again with a different plan is reported as replaced rather than as both added and removed, for example "Subscription Packages (Starter → Professional)", and the change summary counts replaced products alongside added and cancelled ones. While a draft edit is in progress, CPQ compares the draft against the version the customer is currently looking at and generates the summary with AI, refreshing it when the underlying changes change and falling back to a plain generated summary if the AI service is unavailable.

The same summary is shown to the sales rep when reviewing the draft before sending and to the customer as the description of what changed in the updated-version email, so it is kept brief. When a revision changes many things, the summary condenses the other changes first and keeps discounts and pricing complete; a summary that is still too long is cut at the end of a line and ends with an ellipsis. A long summary or a long recipient list never prevents an updated version from being sent.

### Editing a Sent Quote

When a sales rep edits a sent quote, CPQ creates a draft overlay. The customer continues to see the last sent version until the updated version is explicitly published. The sales rep can compare the draft to the customer-facing version before sending.

Discarding the draft restores the quote exactly as it was in the last sent version — header details, subscription terms, products, charges, tier ladders, ramp periods, discounts, bill-to details, and totals — with no impact on what the customer sees. Custom field values entered against charges and products survive the restore, and contacts are left alone because they are operational rather than part of the quoted content. Billing data the customer submitted after the quote was sent is preserved rather than being wiped by the restore, unless the bill-to party itself changed.

If an approval rule is triggered during a draft edit, the approval runs in the editing overlay context without interrupting the customer-facing status. The updated version cannot be sent while its changes are waiting for approval, or while they need an approval that has not been given — CPQ refuses the send and states the reason, so the changes have to be submitted for approval first. Once they are approved, **Send Update to Customer** is offered and the updated version can go out.

***

## 9. The Customer Quote Page

When a quote is sent, the customer receives an email with a link to a secure, hosted quote page. The page does not require a login and is secured with a per-quote access token. Each contact on the quote can be given their own link, which identifies them when they read or send messages.

The access token has a configurable expiration period. After expiry, or when a magic link is always required, customers must request a fresh link via their email address.

Where sales rooms are switched on, a seller can share the quote as a branded sales room instead of this page — see [The Sales Room](#10-the-sales-room).

### What the Customer Sees

* Quote summary: name, number, validity dates, and status, and who the quote is invoiced to when that differs from the customer
* Key dates: subscription start, or the effective change date on an amendment, plus subscription type and, for a termed subscription, the initial term
* Product and charge table with quantities in each charge's unit of measure, prices, and totals, grouped either by charge or by product according to the legal entity's preference
* For Tiered and Volume charges, the per-tier pricing breakdown, listing only the bands the line's quantity reaches (see [Tier Bands on the Customer Page](#tier-bands-on-the-customer-page))
* For Credits charges, the grant and its terms (see [Credit Terms on the Customer Page](#credit-terms-on-the-customer-page))
* On an amendment, the charges split into a **Subscription changes** card, holding the charges this amendment adds, modifies, or ends and those it cancels, and a collapsible **Not affected by this change** card with a count of the charges carried over from the current subscription. The split is made charge by charge, so a product with one changed charge can appear in both cards with a partial total in each, and charges added by an earlier amendment appear as carried over.
* On a ramped quote, the charges laid out period by period — see [Ramped Quotes on the Customer Page](#ramped-quotes-on-the-customer-page)
* Order-level discounts, with their description, value, applicable date range, and the charges they apply to
* The summary of committed totals, and where consumption forecasts exist, the estimated usage breakdown alongside them
* Remarks from the sales team, which the customer can also add to
* Any custom fields configured as customer input (see [Custom Fields](#12-custom-fields))
* Version history, if the quote has been revised, with change summaries
* The other contacts on the quote, where enabled, so the customer can see and invite colleagues
* A messaging interface for communicating with the sales team
* A PDF download, and once signing completes, the signed document

On an amendment, a charge already cancelled in Younium is listed under **Not affected by this change**, with its price and the date it ends, and is left out of the product totals.

Everything on the page is presented with the seller's branding, so the customer sees the seller's identity rather than Younium's.

### Tier Bands on the Customer Page

A Tiered or Volume charge lists its price bands beneath the charge line. The list stops at the band the line's quantity reaches: bands that start above the quantity are left out, so a quantity of 600 on a ladder with bands at 0–100, 101–200, 201–400, 401–600 and 601+ shows the first four bands. The first band is always shown, so a line with a quantity of zero still has a price on the page.

Consumption charges have no committed quantity, so they always list every band. On an amendment, bands the change removes are shown as cancelled under the same rule: a cancelled band appears only if the line's quantity reaches it.

### Credit Terms on the Customer Page

A [Credits charge](#credits-charges) shows the credits granted — for example "5,000 credits every month" — followed by its terms: when unused credits expire, whether they roll over at renewal, whether usage beyond the credits is billed (with the overage price) or only tracked, and the top-up price where one is set. **How credits are used** expands the rate card. A top-up is marked **Top-up** and refers to the charge whose terms it shares.

On an amendment, a changed term or rate shows its previous value alongside the new one. The low-balance threshold and whether free grants appear on invoices are never shown to the customer, and a change to only those settings does not mark the line as changed. The credit terms are shown in every language the customer page supports.

### Ramped Quotes on the Customer Page

On a [ramped quote](#ramp-periods), the product list is divided into one section per period, introduced with the note that pricing changes over the term and that each period is priced on its own. Each section is headed with the period's name, its dates, and its length, together with what the period is worth over its own length and its recurring rate. Where order-level discounts reduce a period, the undiscounted value is shown struck through beside the discounted one. Within each section, charges follow the legal entity's **Product grouping**, by charge or by product.

A stepped contract has no single recurring rate, so the summary on a ramped quote shows the **Total contract value** and, where discounts apply, the **Total discount**, rather than per-period recurring, usage, and one-off rows.

### Preview Mode

Sales reps can open a quote's customer page in **Preview Mode** to see exactly what the customer will see. Preview Mode is fully read-only: the billing-data form, custom-field inputs, messaging, and the accept and sign actions are all disabled, so a rep cannot submit information on the customer's behalf or advance the quote while previewing. Views in Preview Mode are not tracked as customer views.

### Customer Actions

Depending on configuration, the customer can accept the quote, decline it, request changes, or send a message. If e-signing is configured, acceptance triggers the signing flow instead of direct acceptance, and only the designated signer can complete it.

Acceptance is blocked while any of the following is outstanding: required billing data has not been submitted, a required customer-input custom field is empty, a billing address is missing where one is needed for invoicing, or signing is paused. The page states which of these is holding the quote up rather than simply disabling the button.

The page also becomes read-only when the quote has been accepted, declined, or expired, and while a reopened quote is being reworked by the seller.

### Settings

Configured under **Settings → Quote Page**, in two groups: Access & Flow and Content & Layout.

| Setting                               | Description                                                                                                            | Default   |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------- |
| **Enable customer-facing quote page** | When off, quotes use the email-only flow with manual accept and decline by the rep                                     | On        |
| **Enable messaging**                  | Customers can message the sales team from the quote page                                                               | On        |
| **Allow change requests**             | Customers can send a free-text note asking for changes to the quote                                                    | On        |
| **Always require magic link**         | Every visit requires a one-time email verification                                                                     | Off       |
| **Quote link expiration**             | Days before the quote link stops working                                                                               | 30        |
| **Show version history**              | Shows version history to the customer                                                                                  | On        |
| **Show contacts card**                | Shows the contacts card                                                                                                | On        |
| **Show Download PDF button**          | Offers a PDF download                                                                                                  | On        |
| **Show customer notes**               | Shows the remarks section                                                                                              | On        |
| **Show custom fields**                | Shows the custom fields section                                                                                        | On        |
| **Hide "Powered by Younium" badge**   | Hides the "Powered by Younium CPQ" badge in the page footer                                                            | Off       |
| **Product grouping**                  | Presents charges as their own rows (By charge) or grouped under their parent product with a roll-up total (By product) | By charge |
| **Footer text**                       | Plain-text note shown above the page footer                                                                            | —         |

> **Note on hiding custom fields:** Turning off the custom fields section changes only what is displayed. A custom field marked as required for the customer still blocks acceptance, so a field should be made optional rather than hidden if it is not needed.

***

## 10. The Sales Room

A **sales room** is a branded deal page that a seller can share with the customer in place of the standard quote page. It presents the same quote — pricing, the proposal, the information the customer has to provide, and the accept, decline and sign actions — inside a page the seller composes from tabs and blocks: a personal welcome, a recap of the deal, a mutual action plan, case studies, documents and videos from the content library, and calls to action. Messages, the people on the deal and the quote's version history stay one click away beside the page. A room can be presented to the customer in any of eight languages.

Sales rooms are switched on per legal entity. Administrators build **templates** that set the starting content of every room and lock what sellers may not change. Each quote then has its own room, seeded from a template and adjusted by the seller for that deal, so the same standard material reaches every customer while each room still speaks to its own deal. The files and links a room shows come from the legal entity's shared **content library**.

A sales room is a form of the customer quote page, so everything in [The Customer Quote Page](#9-the-customer-quote-page) applies to it: the per-contact links, link expiry and magic links, Preview Mode, the quote page settings, and the rules that block acceptance. When **Enable customer-facing quote page** is off, quotes use the email-only flow and no room is shown.

### Content Library

The **Content Library** holds everything a seller hands to a buyer: case studies, onboarding plans, pricing sheets, decks, videos and links. It is shared by everyone on a legal entity, and content added under one legal entity is not visible under another. Any signed-in user can add, edit, archive and delete content.

Content is organised in folders, which can be nested up to six levels deep and carry a description shown when the folder is opened. Each item has a title, a description, tags, an owner and the date it was last modified, and can be filtered by tag, type, owner and modification date, shown as a list or a grid, and moved, tagged, archived or deleted one at a time or in bulk. Deleting a folder never deletes content: its content and subfolders move up one level.

| Content   | Accepted                                                                                                                                                                                                           |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Files** | PDF; Word, Excel and PowerPoint documents; plain text, Markdown and CSV files; PNG, JPEG, GIF and WebP images; and MP4, WebM and QuickTime videos. Up to 50 MB per file, and a file's contents must match its type |
| **Links** | A web address, including YouTube, Vimeo and Loom videos. CPQ reads only publicly reachable pages                                                                                                                   |

Every file and link is read by AI when it is added. AI writes a title, a description of when a seller would use the item, a summary and the item's category and language, and suggests tags, which the user can accept or dismiss. Title and description can be edited at any time, and the analysis can be run again on request. The same reading powers the library's search: **Search** matches titles, descriptions and tags across the whole library, while **AI** search ranks items by meaning and shows the passage that matches. A question can also be sent to the CPQ Agent, which answers from the library and lists the items it used as sources.

A room never keeps its own copy of a library item; it shows the item from the library. Editing an item therefore changes it in every room and template that shows it. **Archiving** an item takes it out of the library but keeps it in the rooms and templates that already use it, and an archived item can be restored. **Deleting** an item removes it from every room and template that uses it and cannot be undone.

### Sales Room Templates

Templates are managed under **Settings → Sales Room** by administrators, shown as a grid of previews that can be searched by name. When sales rooms are on and a legal entity has no templates, the page offers **Generate default template**, which creates a published template named **Default**, sets it as the default, and fills it with every kind of sales room block across three tabs: **Proposal**, **Working together**, and **Welcome aboard**, which the customer sees only once the quote is signed or converted. Until a template exists, quotes have no sales room.

A new template starts as a **Draft** named *Untitled template*, with the same starting content. Drafts are visible only to administrators and cannot be chosen for a quote until they are published, and only a published template can be the **default** — the one new quotes start their room from. Exactly one template is the default at a time. A template can be duplicated — the copy is a draft named after the original with "(copy)" added — and any template other than the default can be deleted. Every room holds its own copy of its template's content, so editing or deleting a template never changes rooms that already exist.

A template is edited like the room itself (see [Tabs and Blocks](#tabs-and-blocks)), with its **Template name**, **Description**, **Customer language** and **Default template** in the header and its cover under **Change cover** (see [Branding and Cover](#branding-and-cover)).

### Tabs and Blocks

A room is a document of one or more **tabs**, each made up of **blocks**. Tabs can be added, renamed, duplicated, reordered and deleted, and the side menu of each tab is built from its headings. Blocks are added from a menu opened by typing `/`, rearranged by dragging, set side by side in two, three or four columns, and formatted with markdown shortcuts and a floating toolbar. A room saves as the seller types.

| Group               | Blocks                                                                                                                                                                                                                                                                                  |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Basic blocks**    | Text, Heading 1–3, Bulleted list, Numbered list, Quote, Callout and Divider                                                                                                                                                                                                             |
| **Layout**          | 2, 3 or 4 columns                                                                                                                                                                                                                                                                       |
| **Sales room**      | **Welcome**, with a greeting, headline, intro and the quote number, who prepared it, its validity date and status; **Mutual action plan**, a list of steps, each with an owner, a due date and whether it is done; and **Call to action**, a title, text and a button that opens a link |
| **Library & media** | **Resources**, library links and case studies shown as cards; **Attachments**, library documents listed for download; **Library item**, one image, video, PDF or link shown inline; and **Video embed**, a YouTube, Vimeo or Loom video                                                 |

Five further blocks show the quote itself and are filled in when the customer opens the room. Each appears at most once in a room:

| Block                      | What the customer sees                                                                                                                                                                                                                                                                                                         |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Quote details**          | Who is invoiced, when that differs from the customer; the order date on a one-time sales order, or the subscription start on a new subscription; the subscription type; and, for a termed subscription, the initial and renewal term                                                                                           |
| **Products & Services**    | The products, charges, discounts and summary, presented as on the quote page — including the period-by-period breakdown of a ramped quote and the subscription changes view on an amendment. The block can show line discounts as **Net price** or as **List + discount**. Pricing is part of every room and cannot be removed |
| **Proposal**               | The quote PDF, shown inline with a **Download PDF** button                                                                                                                                                                                                                                                                     |
| **Additional information** | The information the customer has to provide: the custom fields configured for customer input and, where required, the billing information form                                                                                                                                                                                 |
| **Notes**                  | The customer's remarks for the order                                                                                                                                                                                                                                                                                           |

Links in a room open only web, email and telephone addresses; any other kind of link is removed.

### Merge Fields

Typing `{{` in any text offers the fields a room can fill in when the customer opens it. Besides the quote, customer and other fields available to [PDF templates](#16-pdf-generation-and-templates), a room has its own:

| Merge field           | Filled with                                                                                                                                                                                                            |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **RecipientName**     | The name of the contact viewing the room                                                                                                                                                                               |
| **SenderName**        | The name of the room owner                                                                                                                                                                                             |
| **SellerCompanyName** | The seller's company name from branding                                                                                                                                                                                |
| **CustomerName**      | The customer's name                                                                                                                                                                                                    |
| **QuoteNumber**       | The quote number                                                                                                                                                                                                       |
| **ValidUntil**        | The date the quote is valid until, written the way the room's language writes dates                                                                                                                                    |
| **Language**          | The room's customer language                                                                                                                                                                                           |
| **QuoteStage**        | Where the quote stands: Draft while it is prepared; Presented once it is sent, including while it is accepted or awaiting signature; Won once it is signed or converted; and Lost once it is declined, lost or expired |

A merge field for a quote custom field is filled with the field's value for the quote, and left blank when the field has no value.

### Visibility Rules and Locks

Any block or tab can carry a **visibility rule**, so the customer sees it only when the rule is met: when a product on the quote has, or does not have, a given product tag; when a quote field has a value, is empty, or equals a given value; or, for anything else, a condition written in the same language as PDF templates. A block or tab whose rule is not met is never sent to the customer.

In a template, a block or tab can also be **locked for reps**. A locked block or tab cannot be changed, hidden or deleted in a room, and CPQ restores it from the template whenever the room is saved, so it cannot be changed by any route. A room keeps its template's locks even after the template is deleted.

### Branding and Cover

Buttons, links and highlights in the room use the colours from [Branding](#19-branding), and the header carries the seller's logo. Above the tabs, each room has a cover: the brand gradient, an uploaded image, or no cover. A template sets the cover its rooms start with, and the seller can change it per room.

A room can also show the **buyer logo** beside the seller's, as *You × Customer*. The seller can fetch the logo by the customer's domain — CPQ suggests one from the customer's website or the contact's email address — or upload it. Until a logo is added, the customer's name is shown. A template sets whether its rooms show a buyer logo.

### The Sales Room on a Quote

While sales rooms are on, the last step of the quote wizard has a **Sales Room** panel with the published templates, the default one selected. The seller can choose another, or switch the panel off to send the customer the standard quote page. The quote then carries a **Sales Room** card with **Create sales room** or **Edit room**, and **Publish** or **Unpublish**. Only the quote owner can edit the room.

The room editor has **Editor** and **Insights** tabs, **Preview**, and a menu with **Settings** and **Share**. Under **Settings**, the seller chooses the room's **Template** — switching replaces the room's content with the new template's — its **Language**, the **Room owner**, who is presented to the customer as their account contact and starts as the quote owner, and its branding. **Preview** opens the room exactly as the customer sees it, under the same rules as Preview Mode.

**Build with AI** has the CPQ Agent rebuild the room from a template for this deal: it writes a personal welcome, a recap and a mutual action plan from the quote and the seller's brief, and, when asked, adds the most relevant content from the library. It replaces the room's current content. Library content is chosen by relevance alone, so the result should be reviewed before the room is published.

Cloning a quote copies its room; the room owner is reset to the new quote's owner.

### Publishing

A room reaches the customer only once it is **published**, and a room can go live before the quote is sent. Until the quote has been sent, the room shows a *Your proposal is on its way* card in place of the quote details, pricing, proposal and the information the customer has to provide: prices and the quote PDF are withheld until then. **Share** lists a link anyone can use and a personal link for each contact, which tells the seller who viewed what.

Publishing takes a snapshot. Later edits are saved to the room but the customer keeps seeing the published version until the seller chooses **Publish changes**; sending the quote also publishes the room's latest version. A room created on a quote that has already been sent starts unpublished.

**Unpublish** sends the customer the standard quote page instead. The room's content is kept and returns when it is published again. The customer's links — in the quote email, in reminders and in a refreshed magic link — lead to the room while it is live and to the standard quote page otherwise, and each kind of link forwards to the other when it does not apply.

Room content is not part of the quote's versions: the customer always sees the room as it was last published, including while an updated version of the quote is being prepared.

### What the Customer Sees in the Room

The room opens with the cover and a header carrying the seller's logo and, where shown, the buyer's, the deal named as the customer and the seller side by side, and the quote's status. Below come the room's tabs and, beside each tab, an **On this page** menu built from its headings and blocks. While required information is missing, **Info needed** is marked with the number of fields still to complete.

A rail on the right edge opens **Messages**, **Collaborators** — the quote's contacts and who signs — and **History**, the quote's version history. Each appears when **Enable messaging**, **Show contacts card** or **Show version history** respectively is on.

The customer accepts, declines, requests changes and signs from a bar at the bottom of the room, under the same rules as on the quote page; where e-signing applies, the signing form opens from the room and returns the customer to it. The page footer shows the **Footer text** and, unless the badge is hidden, a "Sales room powered by Younium" note.

Downloading a library document is recorded on the quote's timeline as *Customer downloaded an attachment*, and downloading the quote PDF as a PDF download. Nothing is recorded in a preview.

### Insights

The editor's **Insights** tab shows how the customer engages with the room: **Views**, **Viewers**, **Avg. time**, **Downloads** and **Clicks**, when it was last viewed, and a chart of views over the last 7, 30 or 90 days. Below it, **Activity** lists each visit, tab opened, item viewed or downloaded and link clicked; **Viewers** lists who visited, by name for a personal link and as an anonymous visitor for the shared link; and **Most engaged content** ranks the room's content by the attention it received. Visits in a preview are not counted.

### Customer Language

Each room has a **customer language**: English, German (**Deutsch**), Swedish (**Svenska**), Dutch (**Nederlands**), French (**Français**), Danish (**Dansk**), Norwegian (**Norsk**) or Finnish (**Suomi**). A template sets the language its rooms start in, and the seller can change it per room.

The room presents its own text — headings, labels, buttons, forms, status messages and the expired-link screen — in that language, and writes dates and quantities the way the language writes them. Content the seller writes — tabs, blocks, product names, library titles and custom field names — appears exactly as written, so a template's text should be written in its customer language. Amounts keep the formatting of the quote's currency. The standard quote page, CPQ itself, emails and the quote PDF are not translated.

### Settings

Configured under **Settings → Sales Room**.

| Setting                | Description                                                                                                                                                                          | Default |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| **Enable sales rooms** | Lets sellers share a quote as a branded sales room instead of the standard quote page. When off, no room panel appears on quotes and every customer receives the standard quote page | Off     |

Each template carries its own settings:

| Setting                                | Description                                                                                                                                            | Default             |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
| **Template name**                      | The name sellers choose the template by. Required, and unique within the legal entity                                                                  | *Untitled template* |
| **Description**                        | When sellers should use the template                                                                                                                   | —                   |
| **Customer language**                  | The language rooms created from the template start in                                                                                                  | English             |
| **Default template**                   | Makes this the template new quotes start their room from. Only a published template can be the default, and only one template is the default at a time | Off                 |
| **Cover**                              | The cover rooms start with: brand gradient, uploaded image or no cover                                                                                 | Brand gradient      |
| **Buyer logo**                         | Whether rooms show the customer's logo beside the seller's                                                                                             | On                  |
| **Lock for reps** (per block or tab)   | Keeps the block or tab exactly as the template sets it in every room                                                                                   | Off                 |
| **Visibility rule** (per block or tab) | Shows the block or tab only when the rule is met                                                                                                       | None                |

***

## 11. Customer Data Collection

Before a customer can accept a quote, CPQ can require them to provide structured billing data. This is controlled by **Require Customer Data Before Acceptance**, and which fields are asked for is configured per legal entity.

### Configurable Fields

| Field                        | Description                                                          |
| ---------------------------- | -------------------------------------------------------------------- |
| **Billing Address**          | Address line 1 and 2, city, state, postal code, country              |
| **Organization Number**      | Company registration number                                          |
| **VAT Number**               | Tax registration number                                              |
| **Invoice Reference**        | Internal reference (e.g. cost centre, PO number)                     |
| **Billing Contact**          | Billing contact name and email if different from the primary contact |
| **Invoice Email**            | Address invoices are sent to                                         |
| **Reminder Email**           | Address payment reminders are sent to                                |
| **Invoice Delivery Method**  | How invoices are delivered                                           |
| **E-invoice Address Scheme** | The electronic invoicing scheme identifying the recipient            |
| **E-invoice Address**        | The recipient's electronic invoicing address                         |

Invoice delivery method accepts Email, Print, Electronic Invoice, External Print, and Automatic Electronic Routing, and is passed through to Younium as selected. When the invoice delivery method is one of the requested fields, the invoice email is asked for only when the customer chooses **Email**; when it is not requested, the invoice email follows the configured field set.

> **Note on the e-invoice fields:** The e-invoice scheme and address are only required when the invoice delivery method is **Electronic Invoice**. They are not requested for any other delivery method, including Automatic Electronic Routing, and the requirement updates live as the customer changes the delivery method. The two fields are always configured as a pair.

### VAT and Organisation Number Validation

A VAT number entered with a recognised EU country prefix is validated against the EU VIES service, both when a sales user enters it on the quote and when a customer submits it on the quote page. The result is shown next to the field, with an explanation available in place:

| Result           | Meaning                                                                                                                                 |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Valid**        | VIES confirmed the number.                                                                                                              |
| **Invalid**      | VIES rejected the number. The form cannot be submitted until it is corrected.                                                           |
| **Unverifiable** | The number could not be checked — the country is outside VIES coverage, or the service did not respond. This does not block submission. |

Numbers for countries outside VIES coverage are reported as unverifiable without a lookup, and a VIES outage is treated the same way, so a service problem never prevents a customer accepting a quote. A Norwegian VAT number is the exception: Norway is outside the EU and VIES has no coverage of it at all, so the field shows no result rather than Unverifiable. The customer account and the bill-to account are validated independently.

The organisation number is captured as entered and is not externally validated. Both the VAT and organisation number are pre-filled from the Younium account, including on amendments, and are written back to Younium on conversion.

### Billing Address

A billing address is required for invoicing. Where the quote already has one — from the customer account or the bill-to account — the customer is not asked again. Where customer data collection is switched off entirely, or the address is already part of the configured field set, CPQ does not ask for it separately. Only when an address is genuinely missing does the quote page ask for one before allowing acceptance.

### Where Submitted Data Goes

When the quote has a separate bill-to account, the data the customer submits is applied to that account, and the form makes clear which company is being invoiced. Invoice reference and billing contact are always held on the quote itself. On conversion, the account details are written to Younium along with the subscription.

### Settings

Configured under **Settings → Customer Data**.

| Setting                                     | Description                                                       | Default |
| ------------------------------------------- | ----------------------------------------------------------------- | ------- |
| **Require Customer Data Before Acceptance** | Customers must fill in the required fields before they can accept | Off     |
| **Required Fields**                         | Which of the fields above are requested                           | None    |

***

## 12. Custom Fields

Custom fields allow organisations to extend the data model of CPQ entities. They can be used to capture additional information during quoting, display it to customers on the quote page, and sync values to Younium upon conversion.

### Supported Entities

Custom fields can be defined for Quote, Quote Product, Quote Charge, Product, Charge Plan, Charge, and Account. Values sync to the corresponding Younium entity — a quote field to the order, a quote product field to the order product, a quote charge field to the order product charge, and an account field to the account. Which field on that entity receives the value is set in the Younium field mapping (see [Younium Sync](#younium-sync)).

### Field Types

Text, Text Area, Number, Decimal, Date, Date/Time, Boolean, Picklist, Email, URL, Currency.

### Behaviour Options

The first five are set on the field itself under **Settings → Custom Fields**. The last two — what the customer sees and must fill in — are set under **Settings → Customer Data**, in the Custom Fields on Quote Page section.

| Option                                   | Description                                              |
| ---------------------------------------- | -------------------------------------------------------- |
| **Required (mandatory for sales users)** | Field must be filled before the quote can proceed        |
| **Visible on quote**                     | Field appears in the quote builder interface             |
| **Editable on quote**                    | Field can be edited, rather than shown read-only         |
| **Editable after acceptance**            | Field can still be edited once the quote is accepted     |
| **Display Location**                     | Where the field appears — see below                      |
| **Customer can input**                   | Field is shown to the customer on the public quote page  |
| **Required before accept**               | Customer must fill this field before accepting the quote |

Fields also support a placeholder, help text, length and value limits, picklist options, a validation pattern with its own message, grouping, and sort order.

A field with a default value starts with that value on every new quote, including clones, revisions and amendments, and on every product and charge added to a quote. A value already in place, such as one copied from the product catalogue or imported from the HubSpot deal, takes precedence. The stored default counts towards required-field checks and is sent to Younium on conversion like any other value.

### Display Location

Quote-level custom fields can be shown either in the quote header card or in a dedicated Additional Information panel. Account-level fields can be shown inline on the customer card, alongside the billing details they relate to, or in the Additional Information panel. On the customer quote page, all customer-input fields are presented together in a single Additional Information section regardless of where they sit for the sales user.

### Where Required Fields Block Progress

Required custom fields are enforced at the point where the missing information would cause a problem:

| Point                                         | What is checked                                                        |
| --------------------------------------------- | ---------------------------------------------------------------------- |
| Selecting the customer in the quote wizard    | Required Account fields                                                |
| Adding products in the quote wizard           | Required Quote Product fields                                          |
| Sending a quote or submitting it for approval | Required fields across Quote, Account, Quote Product, and Quote Charge |
| Customer accepting the quote                  | Fields marked required for the customer                                |

Fields marked as customer input appear on the hosted quote page for the customer to complete, whether or not they are required — so optional information can be gathered without blocking the deal. The form stays editable until the customer saves it, and can be revisited afterwards. It locks once signing is under way, so the document being signed cannot change beneath it. On conversion, the values the customer entered are mapped through to Younium along with the rest of the quote's custom fields.

Custom field values are also available to PDF templates, so they can be rendered in generated documents (see [PDF Generation and Templates](#16-pdf-generation-and-templates)).

### Younium Sync

Quote, account, quote product, and quote charge custom fields are written to Younium when a quote converts. Definitions can also be imported from Younium's field configuration. An imported field takes the matching CPQ field type, and a Younium List field becomes a picklist carrying the list's options and its default option.

**By default**, a custom field is sent to the Younium custom field with the same name on the corresponding entity, with no configuration needed. The default never writes a standard Younium field, even when the CPQ field's name matches one. **Field mapping**, in the Younium integration settings, overrides that default: an administrator maps a CPQ custom field to a field picked from the list of fields Younium holds for that entity — a Younium custom field or one of its standard fields — or turns sending off for that field. A custom field's settings show where its value goes, read-only, with a link to the mapping. Each mapping belongs to one legal entity.

| Younium entity    | CPQ fields that can be mapped to it |
| ----------------- | ----------------------------------- |
| **Order**         | Quote custom fields                 |
| **Account**       | Account custom fields               |
| **Order product** | Quote Product custom fields         |
| **Charge**        | Quote Charge custom fields          |

Each mapping row has a **Sync** setting:

| Sync              | Effect                                                                                |
| ----------------- | ------------------------------------------------------------------------------------- |
| **CPQ → Younium** | The field's value is written to the chosen Younium field on conversion and amendments |
| **Off**           | The row is kept, but the value is not sent to Younium                                 |

Deleting a mapping returns the field to the default, so its value goes to the Younium custom field with the same name again. The mapping table can be filtered by Younium entity, and a **Needs attention** filter lists the rows that have a problem.

**Rules that keep mappings valid:**

* **One CPQ field per Younium field.** Two active mappings cannot write to the same Younium field on the same entity; the first must be turned off before another CPQ field can take its place. A field that is only following the default does not hold a standard Younium field that shares its name, so another CPQ field can still be mapped to that standard field.
* **Compatible types only.** A field is offered only for CPQ field types that fit it:

  | Younium field holds   | CPQ field types accepted  |
  | --------------------- | ------------------------- |
  | Text                  | Any                       |
  | Whole numbers         | Number                    |
  | Numbers with decimals | Number, Decimal, Currency |
  | Dates                 | Date, Date/Time           |
  | Yes/no values         | Boolean                   |
  | A list of options     | Picklist, Text            |

  Younium fields of any other kind are shown with the reason **Not supported for mapping**.
* **Fields CPQ sets itself are not offered.** Standard fields that CPQ fills from the quote — such as the account, currency, dates and terms, payment terms, remarks, VAT number, organisation number, and invoice email — are shown as unavailable with the reason **Set by CPQ from the quote**. These built-in fields always sync and are shown as locked rows at the top of the table.
* **Standard fields CPQ cannot send are not offered.** A standard Younium field is available only where CPQ can write it on every request it sends for that entity — for an order field, on new subscriptions, sales orders, and amendments alike; others are shown with the reason **CPQ can't send this field to Younium**.

A mapped standard field is written onto the record itself, taking precedence over the value CPQ would otherwise set; a mapped custom field is written to the record's custom fields. If a mapped Younium field no longer exists, the row is marked **Missing** and the value is not sent. The list of Younium fields is refreshed automatically every 15 minutes, or immediately with **Refresh fields**.

**When mapped values are written:**

| Conversion                              | Order fields | Account fields                         | Order product and charge fields |
| --------------------------------------- | ------------ | -------------------------------------- | ------------------------------- |
| New subscription or sales order         | Written      | Written to the new or existing account | Written                         |
| Amendment (change, or renew and change) | Written      | Written to the existing account        | Not written                     |

> **Note on a custom field named after a standard field:** A CPQ custom field whose name matches a standard Younium field — for example a quote field named after **Invoice batch group** — is sent to a Younium custom field of that name, not to the standard field. To fill the standard field, map the CPQ field to it in **Field mapping**; the mapping is kept even though both names are the same.

> **Note on fields mapped before field mapping existed:** Custom fields that were previously sent to a Younium field with a different name, to a different Younium entity, or not sent at all, keep that behaviour as mapping rows. Where two fields previously wrote to the same Younium field, only one keeps sending and the other is turned off.

Besides Younium custom fields, a CPQ field can be mapped to one of a fixed set of Younium standard fields. Every field on the list can be written by CPQ:

| Younium entity | Standard fields offered                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Order          | Description, Remarks, Your reference, Our reference, Your order number, Buyer reference, Use account invoice batch group, Disable invoicing, Invoice batch group                                                                                                                                                                                                                                                     |
| Account        | Name, Our reference, Your reference, Invoice email address, Invoice email CC addresses, Invoice delivery method, Tax registration number, Organization number, Electronic invoice address, Electronic invoice address scheme, Tax template, Accounts receivable, Invoice batch group, Invoice setting group, Reminder email address, Attach UBL to invoice, Attach ZUGFeRD XML to invoice, Disable invoice reminders |

Order fields are written when a quote creates a subscription or sales order and when an amendment changes or renews one; account fields are written when the account is created or updated. The list of Younium custom fields offered for mapping is read from Younium each time the mapping is opened, so a field added in Younium appears without any refresh.

> **Note on Invoice separately:** The order's **Invoice separately** field is not offered for mapping. CPQ always sends **Our reference** on an order, and Younium does not accept an order that both carries Our reference and has Invoice separately switched off.

***

## 13. Contacts and Messaging

### Contacts

A quote carries its own contacts, managed in CPQ rather than synced from Younium. Each contact has a name, email, phone, title, and a role such as Decision Maker, Technical Evaluator, Budget Approver, Legal / Procurement, Executive Sponsor, or End User. Contacts can carry an internal comment that the customer never sees.

Exactly one contact is the **signer** — the person who can accept the quote and complete e-signing. The first contact added becomes the signer, and the signer can be reassigned later; reassigning while an e-signing envelope is active voids that envelope.

Contacts can be invited to the quote, each with their own link. On the quote page, a customer can see the other contacts, invite colleagues, edit their own details, and remove themselves. Email addresses are fixed once set, so a contact's identity cannot be changed after they have been invited.

When a quote is created for an account that has been quoted before, contacts can be imported from that account's previous quotes rather than retyped, skipping anyone already on the quote.

> **Note on the billing contact:** The billing contact captured during customer data collection is an invoicing detail on the quote, not a contact with access to the quote page.

### Messaging

Every quote includes a built-in messaging channel between the sales team and the customer.

Messages are classified as:

* **Customer messages**: Visible to both the sales team and the customer. Sending a customer message when the quote is in *Sent* or *Viewed* status moves the quote to *Awaiting Response*.
* **Internal notes**: Visible only to the sales team. Used for deal strategy, internal context, or AI-generated suggestions.

When a seller replies to a customer message, the quote status returns from *Awaiting Response* to *Sent*.

### Remarks

Separately from messaging, a quote carries **remarks**: a note that is part of the commercial document rather than a conversation. Remarks are written by the sales team on the quote, shown to the customer on the quote page where the customer can also edit them, rendered into generated documents, and carried to Younium as the subscription's remarks on conversion. Remarks are editable until the quote is accepted, declined, or expired. An amendment starts with the remarks of the subscription it amends, which the sales team can then edit like any other quote's remarks.

### Notifications

Both sides are emailed about new messages: the sales rep when the customer posts one, and the customer when the sales team replies. These emails are sent as standard, with no on/off switch in the settings screens. Whether the messaging channel appears on the quote page at all is a quote page setting — see [The Customer Quote Page](#9-the-customer-quote-page).

***

## 14. E-Signing

E-signing is optional and configured per legal entity. When enabled, quote acceptance triggers an electronic signature flow rather than a simple click-accept.

### Supported Providers

CPQ offers three e-signing providers, set up per legal entity from the E-Signing group under **Settings → Integrations**:

| Provider             | What it is                                                                                                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Younium eSigning** | Built-in e-signing, with no separate account or credentials. Signing requests come from CPQ itself, and signers can be asked to verify their identity with an electronic ID |
| **DocuSign**         | Envelope-based signing through the organisation's own DocuSign account                                                                                                      |
| **PandaDoc**         | Embedded and remote signing through the organisation's own PandaDoc account. Requires a PandaDoc Business plan or higher                                                    |

Connecting a provider — or activating Younium eSigning — is what turns e-signing on, and disconnecting it turns e-signing off. Only one provider can be active at a time, so while one is connected the others cannot be connected and their tiles ask for the active provider to be disconnected first.

### Signing Flow

The standard flow for a quote with e-signing configured:

1. Customer accepts on the quote page. The acceptance is confirmed immediately and the signing document is prepared in the background, so the customer is never left waiting on the provider.
2. Once the document is ready, the quote moves to *Awaiting Signature* and the customer signs — either embedded in the quote page or through the provider's own email, depending on configuration.
3. If a seller counter-signature is required, the quote moves to *Partially Signed* and the seller is notified.
4. Once all parties have signed, the quote moves to *Signed* and the signed document is available from the quote page.

If preparing the document fails, the quote reports the failure on the quote page instead of appearing to have stalled, and the seller can start signing again.

The signing document is generated from the quote's document template with the same quote data as the PDF preview and the customer's download, so every merge field — including the contacts, the buyer and seller signatories, the quote owner, discounts, ramp periods, and price tiers — reads the same in the document sent for signature as in the preview.

### Keeping the Quote Owner Informed

The quote owner is told by email when the customer acts on a quote, so they do not have to watch the quote list:

| Moment                                                       | Who is emailed                                                                                                                                 |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| The customer accepts on the quote page, without e-signing    | The quote owner                                                                                                                                |
| The customer signs and the owner is the one who countersigns | The owner, as the seller signatory, receives the existing request to countersign                                                               |
| The customer signs and a colleague countersigns              | The colleague receives the request to countersign; the owner is also emailed that the customer has signed, naming who still has to countersign |
| All parties have signed                                      | The customer receives the completed document as before; the quote owner is emailed that the quote is fully signed                              |

An acceptance the seller records on the customer's behalf sends no owner email. Where the customer accepts without giving a name, the email names the contact viewing the quote, then the signer, then the customer.

The owner email after a customer signature follows **Notify the seller when the customer signs** (see the settings below). The same moments are also sent to the owner as a Slack direct message where Slack is connected — see [Slack](#14-slack).

### Signing Statuses

E-signing status is tracked separately from the quote status:

| E-Signing Status   | Description                                                |
| ------------------ | ---------------------------------------------------------- |
| Configured         | Signers are set up; no envelope sent yet                   |
| Preparing          | Acceptance received; the signing document is being created |
| Sent               | Signing request delivered to signers                       |
| Partially Complete | At least one signer has completed; others pending          |
| Completed          | All parties have signed                                    |
| Voided             | The signing request was cancelled                          |
| Declined           | A signer declined to sign                                  |
| Failed             | The signing document could not be created                  |

The seller signatory is resolved from the quote's designated signer, falling back to the quote owner, so documents are always addressed to a real person.

### Signing Paused State

E-signing can be interrupted and blocked in several ways:

* The seller explicitly cancels the signing request
* A signer is reassigned, voiding the existing envelope
* The seller starts editing the quote while an envelope is active
* The e-signing provider notifies CPQ of a void or decline

When signing is paused, the customer's Accept and Sign action is blocked and the page explains why. The seller can resume by sending a new signing request, publishing an updated version, or explicitly resuming from the signing panel. When signing is resumed, the customer is notified by email so they are prompted to complete signing.

### Younium eSigning

Younium eSigning is part of CPQ, so there is nothing to connect: an administrator activates it for the legal entity and it is ready to use. It is charged per use. Activating it — from its tile under **Settings → Integrations**, or by choosing it in the onboarding wizard — first shows its pricing: a charge for each fully signed contract, and an additional charge for each signer who signs with an electronic ID. Usage is billed monthly on the organisation's regular Younium invoice, and prices exclude VAT. **Activate e-signing** stays unavailable until the administrator confirms that they understand e-signing is charged per signed contract. Changing Younium eSigning's settings afterwards does not ask for the confirmation again. Disabling it asks for confirmation, after which quotes can no longer be sent for signature with Younium eSigning.

Signers receive nothing from a separate e-signing service: every signing request comes from CPQ. The customer signs in a signing window on the quote page, carrying the seller's logo and shown in the language the customer is viewing the quote page in, and the seller counter-signs from the quote in CPQ. When the legal entity's customer-facing quote page is switched off, CPQ instead emails the customer signer a **Signing request** with a personal link to sign. The customer can also decline from the signing window, and the reason they give is recorded with the signing history.

A quote moves to *Signed* only once Younium eSigning itself confirms that every signature is complete, rather than on the signer's browser reporting that signing has finished.

### eID Signing

With Younium eSigning, a signer can be asked to verify their identity with an electronic ID — such as BankID — before signing. The signer chooses their eID provider when signing. Each signer has one of three signing methods:

| Signing method | Description                                                                 |
| -------------- | --------------------------------------------------------------------------- |
| **Standard**   | A standard electronic signature, with no identity verification              |
| **eID (AeS)**  | An advanced electronic signature, with the signer verified by electronic ID |
| **eID (QeS)**  | A qualified electronic signature, with the signer verified by electronic ID |

eID signing is off until **Allow eID signing** is turned on. Once it is, a policy per customer country decides what the customer signer is offered, using the customer's country on the quote:

| Policy          | Customer signer's signing method                            |
| --------------- | ----------------------------------------------------------- |
| **Required**    | eID (QeS), and the seller cannot change it                  |
| **Default on**  | eID (QeS) by default; the seller can change it when sending |
| **Default off** | Standard by default; the seller can change it when sending  |
| **Not offered** | Standard, and the seller cannot change it                   |

A country that is not in the list, and a quote whose customer country is unknown, are treated as **Default off**. The seller's own signer always defaults to Standard and can be switched to either eID method. The seller sees and changes each signer's method in the send dialog, where the customer's signer appears under **Signs on their side** and the seller's under **Signs on your side**; a locked method states that it is required, or not offered, for the customer's country. CPQ checks the policy again when the quote is sent, so a locked method cannot be overridden.

### Signing Records

Younium eSigning keeps a record of every signature on its page, opened from its tile under **Settings → Integrations**, visible to administrators while Younium eSigning is the active provider.

**Documents** holds each fully signed contract: the signed PDF and the audit certificate for the signing, listed with the quote, account, signers, signing date and signature level (Standard, eID · AeS, eID · QeS, or Mixed when the signers used different methods). Each document opens to show its signers and its full signing history, and both files can be downloaded. Documents can be searched by quote, account or submission ID, and filtered by signature level and signing date.

A signed contract can be deleted, which removes the signed PDF and audit certificate from Younium. A deleted contract moves to **Recently deleted**, which shows who deleted it and when, and it can be restored from there. The deletion itself stays in the signing history.

**Transactions** is the signing log: every event in every signing, from the request being sent to the signed documents being stored, with the time, the user or signer, the quote, the customer and the signature level. It can be filtered by quote, customer, sales rep, date, event type, quote status and signature level, and exported as CSV. Entries cannot be edited or deleted.

| Event               | Recorded when                                                                |
| ------------------- | ---------------------------------------------------------------------------- |
| Sent / Resent       | The signing request is sent, or sent again                                   |
| Delivered           | The signing request reaches a customer signer, on the quote page or by email |
| Opened              | A signer opens their signing link                                            |
| Viewed              | A signer starts reviewing the document                                       |
| eID verified        | A signer verifies their identity with an electronic ID                       |
| Signed              | A signer signs                                                               |
| Declined            | A signer declines, with their reason                                         |
| Expired             | The signing request expires                                                  |
| Voided              | The signing request is cancelled, with the reason                            |
| Completed           | All parties have signed and the signed documents are stored                  |
| Document downloaded | The signed PDF or the audit certificate is downloaded                        |
| Document deleted    | A signed contract is deleted                                                 |
| Document restored   | A deleted contract is restored                                               |

For eID signatures, the log shows the eID method used and the signer's personal identity number in masked form only; CPQ does not keep the full number.

When the quote is converted, both the signed PDF and the audit certificate are attached to the order in Younium. If the signed contract has been deleted, no signed files are attached. A quote with a signing history cannot be deleted.

### Settings

Set on the connected provider's page, opened from its tile under **Settings → Integrations**. For Younium eSigning, the settings are on that page's **Settings** tab.

| Setting                                       | Description                                                                                                                                                       | Default                                                                                                                                                        |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Notify the seller when the customer signs** | Prompts the seller to counter-sign without checking the quote list, and tells the quote owner when a colleague is the one who countersigns                        | On                                                                                                                                                             |
| **Notify the customer when fully signed**     | Sends the completed document once all parties have signed                                                                                                         | On                                                                                                                                                             |
| **Allow eID signing**                         | Younium eSigning only. Lets signers verify their identity with an electronic ID before signing                                                                    | Off                                                                                                                                                            |
| **eID (QeS)** per **Customer country**        | Younium eSigning only. The eID policy for customers in each listed country: Required, Default on, Default off, or Not offered. Countries can be added and removed | Sweden, Denmark, Norway and Finland: Default on. United Kingdom, Belgium, the Netherlands, Luxembourg and Germany: Default off. Any other country: Default off |

***

## 15. Slack

Where a Slack workspace is connected, CPQ posts quote activity into Slack and lets approvers act on quotes without leaving it. A workspace is connected per legal entity from the Communication group under **Settings → Integrations**, and an administrator selects the channel that receives team activity. Individual users are additionally linked to their own Slack account, which is what allows CPQ to message them directly and to attribute their actions — see [Linking Slack Accounts](#linking-slack-accounts).

### What Is Posted

| Destination        | Events                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Team channel**   | Approval requested, quote approved or rejected, quote sent, viewed, signing page viewed, accepted, declined, signed by the buyer and awaiting countersignature, signed, converted, expired, and lost                                                                                                                                                                                                 |
| **Direct message** | Approval requested (to each member of the approval group), approval decision (to the quote owner), seller signature required (to the person who signs for the seller), customer signed and awaiting a colleague's countersignature (to the quote owner), quote accepted by the customer (to the quote owner), quote fully signed (to the quote owner), and new customer message (to the quote owner) |

Team channel activity is posted as one thread per quote, so a deal's history stays together. Each message names the quote and customer and carries its value, so the channel is readable without opening CPQ. The value is the total contract value where the quote has a fixed term, so a ramped quote is never reported at its first period's rate alone; Evergreen quotes show their total per period with their one-off total alongside, and sales orders show their one-off total. The quote owner appears as a Slack mention when CPQ can match them to a Slack account in the workspace — through a linked account or the same email address — and by name otherwise.

Approval requests and decisions appear in both places: the team channel records them in the quote's thread, and the people who need to act receive them directly.

The quote owner's direct messages about acceptance and signing follow what the customer does. An acceptance the seller records on the customer's behalf sends no direct message. When the customer signs and a colleague countersigns, the owner's message names the colleague still to sign; the team channel thread records the signature once, as before. These direct messages are sent whatever the owner email settings in [E-Signing](#13-e-signing) are.

The new customer message notification quotes what the customer wrote, up to the first 200 characters, so the owner can read it without opening CPQ. Slack formatting in the message, such as channel mentions or links, is shown as plain text. Only messages from the customer send this notification. The sales team's own replies and internal notes do not, and customer messages are not posted to the team channel.

### Approving from Slack

An approval request arrives as a direct message with Approve, Reject, and Open quote actions. Approving acts immediately; rejecting asks for a reason first, since a rejection reason is always required.

Only a linked Slack user who is a member of an approval group can approve or reject.

### Linking Slack Accounts

CPQ can only message a user directly once their CPQ user is linked to a Slack account in the connected workspace. A user is linked in one of two ways:

| Way                                 | How it happens                                                                                                                                                      |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Automatically, by email**         | CPQ looks for a Slack account in the connected workspace with the same email address as the CPQ user and links the two. The two addresses must be the same.         |
| **By the user, from Notifications** | Each user can connect their own Slack account from **Notifications** in their user menu, by signing in to Slack. This links the account whatever its email address. |

A user who is neither linked nor matched by email receives no direct messages.

***

## 16. PDF Generation and Templates

CPQ can generate a PDF document for any quote. PDFs are rendered by merging quote data into a Word (.docx) template.

### Template Studio

Administrators manage document templates in the Template Studio. Templates use merge fields to insert dynamic quote data. The Template Studio analyses an uploaded template, reports any merge field it does not recognise, and can list the available fields. Template previews render against sample data that includes recurring, one-off, usage-based, and measured charges, dated order discounts, and a discounted tier ladder, so every section of a template, tier sections included, can be checked before it is used.

Templates are maintained per document type — quote, change quote, order confirmation, invoice, and contract — with one default per type for each legal entity. An individual quote can be assigned a specific template to override the default, through the quote's **Template** field. The field offers the active templates of the quote's own type, quote or change quote, and can be changed while the quote is a draft or while a sent quote is being edited. An amendment falls back to the quote template when no dedicated change quote template exists.

Fonts used by a template are embedded when the template is uploaded, so generated documents render consistently regardless of what is installed wherever they are opened. Existing templates were backfilled with their fonts.

### Template Content Restrictions

A template's merge fields may only read the data made available to it; they cannot reach outside that data to inspect application internals, read a file from disk, or fetch a remote address. The Template Studio rejects a template that attempts this when it is uploaded, naming the disallowed construct so it can be corrected.

An image or attached-document merge field must be bound to data supplied in the report — such as a logo or QR code field — rather than to a literal file path or web address; a template that tries to load an image or document that way is rejected in the same way.

> **Note on native Word fields:** A template can also carry native Word fields such as linked pictures or included text blocks. Any such field that would pull its content from an external file or link is removed automatically when the document is generated, even in a template uploaded before this restriction existed.

### Data Available to Templates

| Group                  | Available data                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Quote header**       | Number, name, status, created date, valid from and until, currency, remarks                                                                                                                                                                                                                                                                                                     |
| **Financial metrics**  | MRR, CARR, TCV, estimated TCV, total, estimated total, recurring total, one-time total, total estimated usage, total discount                                                                                                                                                                                                                                                   |
| **Customer**           | Name, account number, full and component address, organisation number, VAT number                                                                                                                                                                                                                                                                                               |
| **Bill-to account**    | Name, account number, address, VAT and organisation number, payment term, invoice delivery method, electronic invoice address and scheme, invoice and reminder email                                                                                                                                                                                                            |
| **Contacts**           | Name, title, email, phone                                                                                                                                                                                                                                                                                                                                                       |
| **Seller and owner**   | Quote owner name, title, email, and phone; seller signatory name, title, email, and phone; seller company name and logo                                                                                                                                                                                                                                                         |
| **Buyer signatory**    | Company name, signatory name, title, and email                                                                                                                                                                                                                                                                                                                                  |
| **Subscription terms** | Start and end date, type, initial and renewal term, auto-renewal, notice period                                                                                                                                                                                                                                                                                                 |
| **Charge lines**       | Product and charge names, description, quantity, unit and list price, extended price, discounts, line total, charge type and model, billing and price period, unit of measure, start and end dates, whether the line ends on its own date rather than with the subscription (on an amendment, a charge already cancelled in Younium), whether the line is optional and selected |
| **Estimated usage**    | Estimated usage and quantity per line, estimated line total, and whether a line is estimated                                                                                                                                                                                                                                                                                    |
| **Credits**            | Per Credits charge: credit type, expiry, rollover, overage behaviour, overage price, and top-up price; the rate card, as a loop of usage types with the credits one unit consumes; and a loop of all Credits charges with a count and a flag for whether the quote has any                                                                                                      |
| **Price tiers**        | Tier number, from and to quantity, unit price after the per-tier discount, list price before it, price base, and per-tier discount                                                                                                                                                                                                                                              |
| **Order discounts**    | Description, type, value, date range, and what each discount applies to                                                                                                                                                                                                                                                                                                         |
| **Ramp periods**       | Per period: number, name, start and end date, length, number of charges, and the period's total with its recurring and one-time parts. Per charge line: its quantity, unit price, discount, and line total in each period                                                                                                                                                       |
| **Custom fields**      | Values at quote, quote product, quote charge, account, product, charge plan, and charge scope, addressed by field name                                                                                                                                                                                                                                                          |
| **Amendment detail**   | Added, modified, cancelled, ending, changed, and unchanged charges and products, with counts; per-tier changes with the old and new unit and list price of each band                                                                                                                                                                                                            |

> **Note on tier unit price vs list price:** Within a tier, the unit price is the band's price after its own tier discount, matching the unit price the customer sees on the quote page, and the list price is the undiscounted band price. A negative tier discount is an uplift, so the unit price can be above the list price. Charge lines follow the same split.

A tiered or volume charge has no single unit price, so its charge-line unit and list price are left blank in every document, including the previous price on an amendment, and its band prices come from the price tiers.

Charge line and order discount dates are always filled where the quote establishes them. A charge with no dates of its own, and not bound to a milestone, shows the subscription term; a line added by an amendment starts on the effective change date. An order discount that runs with the subscription's own term shows the subscription start and term end, and one added by an amendment starts on the effective change date. On a sales order, a discount shows the order date and no end date. One-off charges, and any charge or discount on an evergreen subscription, have no end date.

On an amendment, the list of all charges keeps one continuous line numbering, separate from the numbering within the added, modified, and other change groups.

Templates also expose flags and counts — whether a quote has recurring, one-off, or usage charges, whether it has estimated usage, discounts, or multiple products, and how many of each — so a document can adapt its layout to the quote rather than printing empty sections.

Beyond straight field substitution, templates support conditional content, loops over charge lines, tiers, and ramp periods, tag-based inclusion so a single template can serve several situations, and formatting control over how numbers and dates are rendered. Signature and date placeholders are available for both the buyer and the seller, and are translated to the configured e-signing provider's own anchors.

The PDF the customer opens from the quote page or a sales room — the **Proposal** block and its **Download PDF** button included — is rendered from the same template and data as the seller's preview. Custom field values and sections included for tagged products appear in the customer's copy exactly as they do in the preview, and a custom field with no value prints blank.

### Ramped Quotes in Documents

A template shows the periods of a [ramped quote](#ramp-periods) through a periods loop, which works in two ways. Placed on its own, it repeats once per period, and the period's charges are listed inside it — a document laid out period by period. Placed inside a charge loop, it repeats once per step of that charge line, giving the line's schedule: its quantity, price, discount, and total in each period. On a quote that is not ramped, a periods loop is empty and prints nothing, so one template serves both kinds of quote.

Outside a periods loop, a ramped quote's charge lines and products are listed once each rather than once per period, with the first period's quantity, price, and total, and the recurring total and each product's total are also the first period's. A template without a periods loop therefore prints a ramped quote at its first period's figures, while TCV still covers the whole term.

A period's total is what the period is worth over its own length, after the order-level discounts in force during it — the same figure the customer page shows for that period. Charges priced monthly, quarterly, or annually are all counted over the period's months.

***

## 17. Email Delivery and Tracking

CPQ sends emails for quote delivery, approval notifications, e-signing events, and messaging.

### Email Templates

Each email type has a default template whose subject and body an organisation can override, preview against sample data, and reset. The types are quote sent, change quote sent, approval requested, approval decision, new message, contact invitation, signing request, seller signature required, fully signed, signing voided, signing resumed, quote accepted (to owner), and customer signed (to owner). The quote accepted (to owner) email covers both a customer acceptance and a fully signed quote, with its wording chosen by which one happened. The signing request carries the customer signer's personal link to sign, and is sent only by Younium eSigning when the quote page is switched off.

Seller branding values — company name, logo, brand colours, and fonts — are available as placeholders in every email type, alongside the details specific to that email such as recipient and sender names, quote number, value, total contract value, and the quote link. The default templates show the total contract value where the quote has a fixed term, and the total per period for Evergreen quotes and sales orders.

### Email Tracking

For quote delivery emails, CPQ tracks delivery, opens with their timestamps, clicks on the quote link, and bounces. Tracking events are reflected in the quote's activity timeline.

***

## 18. CPQ Agent (AI Assistant)

The CPQ Agent is an AI-powered assistant integrated into the quoting workflow. It operates on the context of the current quote and product catalog.

> **Advisory only**: All actions proposed by the CPQ Agent require explicit confirmation before being applied. The agent cannot take autonomous action on quotes.

### Capabilities

* **Product search and recommendations**: Natural language search across the product catalog; cross-sell and upsell suggestions based on deal context.
* **Quote analysis**: Reviewing a quote for completeness, risk factors, or pricing consistency.
* **Quote editing**: Adding, removing, or updating charges on a quote — including automatically entering edit mode on sent quotes.
* **Email generation**: Drafting personalised quote emails in configurable tones.
* **Quote naming**: Suggesting a professional quote name based on the customer and products.
* **Customer message analysis**: When a customer sends a message, the Agent analyses it and may suggest a reply or recommend an action.
* **Change summaries**: Describing in plain language what a revised quote changes relative to the version the customer has.
* **Content library answers**: Answering questions from the [content library](#content-library) by meaning rather than keywords, citing the items used as sources.
* **Sales room building**: Reading a quote's sales room, listing the published templates, building a personalised room from a template — welcome, recap, mutual action plan and the most relevant library content — and adding a section, with text and library items, to a room's existing or a new tab. Building a room replaces its current content, so the Agent always asks for confirmation first.

### Confirmation Modes

The confirmation behaviour of the Agent is configurable at the legal entity level:

| Mode                         | Behaviour                                                                                              |
| ---------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Always Ask**               | Every action requires explicit confirmation before execution                                           |
| **Whitelist Only** (default) | Read-only operations execute automatically; write operations require confirmation                      |
| **Never Ask**                | All operations execute automatically, except customer-facing actions which always require confirmation |

### Settings

Configured under **Settings → AI**.

| Setting               | Description                                                                                                                                                                                | Default        |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
| **Enable AI**         | Master toggle for all AI features                                                                                                                                                          | On             |
| **Confirmation Mode** | How the agent handles actions that change data: Always Ask confirms every action, Whitelist Only confirms only the ones that write, Never Ask confirms none except customer-facing actions | Whitelist Only |

***

## 19. Branding

CPQ supports custom seller branding, configured per legal entity. Branding applies both to the customer-facing quote page and to outgoing transactional emails, so the customer experience is consistent across channels.

### Configurable Brand Settings

Configured under **Settings → Branding**.

| Setting              | Description                                                 |
| -------------------- | ----------------------------------------------------------- |
| **Company name**     | Organisation name displayed on the quote page and in emails |
| **Company logo URL** | Web address of the company logo                             |
| **Primary color**    | Primary brand colour (hex)                                  |
| **Accent color**     | Accent brand colour (hex)                                   |
| **Heading font**     | Font used for headings                                      |
| **Body font**        | Font used for body text                                     |

The company logo is also available to PDF templates, and the quote page footer text and the option to hide the "Powered by Younium CPQ" badge are configured with the other quote page settings (see [The Customer Quote Page](#9-the-customer-quote-page)).

***

## 20. HubSpot Integration

Younium CPQ is available as an embedded extension within HubSpot, appearing on deal records as both a tab and a sidebar card. The integration is connected per legal entity from the CRM group under **Settings → Integrations**, where connecting starts the sign-in with HubSpot directly. It uses HubSpot OAuth and requires access to deals, companies, contacts, and line items.

### Capabilities from HubSpot

* View all quotes associated with a HubSpot deal, with the account's recurring revenue summarised
* Create new quotes using a guided wizard, pre-filled with deal, company, and contact data
* Open the full CPQ quote builder in an embedded modal, and clone or delete quotes without leaving HubSpot
* Send quotes to customers and track email delivery, opens, and link clicks
* Complete seller counter-signature when e-signing is configured
* Convert accepted quotes to Younium subscriptions
* Nominate one quote per deal as the **active quote**, which is the quote that drives the deal's value and line items

Users are connected to CPQ through a user mapping so quotes created from HubSpot are attributed correctly; where no explicit mapping exists, CPQ matches on email address within the portal.

### Deal Value

The deal amount CPQ writes is configurable per legal entity:

| Metric             | Value written                                            |
| ------------------ | -------------------------------------------------------- |
| **CMRR** (default) | Monthly recurring revenue                                |
| **CARR**           | Contracted annual recurring revenue                      |
| **TCV**            | Total contract value, including any consumption forecast |

On an amendment, CPQ writes the **change** rather than the absolute figure, so a deal reflects the value the amendment adds. The amount is refreshed when the active quote's content changes and when the quote is created, sent, or synced manually.

The deal amount can also be carried by the field mapping, as a mapping from **MRR**, **CARR**, or **TCV** to the deal's **Amount** property. Each legal entity's chosen deal amount metric has been carried over into such a mapping (CMRR as MRR, CARR as CARR, TCV as TCV), unless a mapping already wrote the amount. The deal amount metric is written first and the field mapping afterwards, so where both write the amount, the mapped value is the one the deal keeps.

### Deal Stage Mapping

CPQ can update HubSpot deal stages when quote lifecycle events occur. Mappings are configured **per pipeline**, so each pipeline maps its own stages to CPQ events. Stages can be mapped for quote sent, viewed, approved, accepted, declined, signed, converted, lost, and expired.

> **Note on pipelines:** CPQ only ever writes a deal's stage, never its pipeline, and it verifies that the mapped stage belongs to the deal's current pipeline before writing. A deal therefore stays in the pipeline its owner put it in. Where no mapping exists for the deal's pipeline, or the mapped stage does not belong to it, the stage is left untouched.

Internal statuses such as Building, Draft, Pending Approval, and Awaiting Signature have no stage mapping, so early-stage quoting activity does not move a deal.

### Line Item Synchronisation

The quote's charges are written to the deal as line items when the quote is sent, and when a user nominates a quote as the deal's active quote. Nominating an active quote replaces the deal's line items with that quote's, and runs in the background so the user is not held up.

Each line carries its name, quantity, unit price, discount, billing frequency, recurring billing dates, and the HubSpot product it corresponds to. On an amendment, only charges that actually differ from the current subscription are written, and each is marked as new or changed, so the deal shows the shape of the amendment rather than the whole subscription. A charge already cancelled in Younium that the quote leaves untouched is not written. Consumption charges without a forecast are written at zero value so the deal total matches the quote.

### Younium Properties on the Deal

CPQ writes Younium's built-in `younium_*` properties by default. They are written each time the quote is saved, and again when it is sent, accepted, and signed. The deal properties are editable defaults: an administrator can point any of them at a different CPQ field or switch it off, except those carrying the Younium order number, order ID, and legal entity, which CPQ manages itself.

| HubSpot deal property                                                                                 | Source                                                |
| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `younium_initial_term`                                                                                | Initial term months                                   |
| `younium_renewal_term`                                                                                | Renewal term months                                   |
| `younium_auto_renewal`                                                                                | Auto-renewal                                          |
| `younium_remarks`                                                                                     | Quote remarks                                         |
| `younium_order_effective_start_date`                                                                  | Subscription start date                               |
| `younium_order_effective_change_date`                                                                 | Effective change date on an amendment                 |
| `younium_change_type`                                                                                 | `new` for a standard quote, `change` for an amendment |
| `younium_order_number`                                                                                | Subscription number                                   |
| `younium_order_id`                                                                                    | Subscription identifier                               |
| `younium_legal_entity`                                                                                | The legal entity the quote belongs to                 |
| `younium_delivery_name`                                                                               | Customer name                                         |
| `younium_delivery_street1`, `younium_delivery_street2`                                                | Customer address lines                                |
| `younium_delivery_zip`, `younium_delivery_city`, `younium_delivery_state`, `younium_delivery_country` | Customer address                                      |

After conversion, CPQ writes back the resulting order: `younium_order_id`, `younium_order_number`, and `younium_order_status` (`active` or `draft`).

Empty values are omitted rather than written as blanks, so CPQ never clears a property it has no value for. A property in this table that does not exist on the connected HubSpot portal is skipped without an error, and the others are still written.

### Younium Properties on Line Items

| HubSpot line item property                                                 | Source                                                         |
| -------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `younium_charge_type`                                                      | Charge type                                                    |
| `younium_charge_model`                                                     | Pricing model                                                  |
| `younium_billing_period`                                                   | Billing period                                                 |
| `younium_order_charge`                                                     | Catalog charge number                                          |
| `younium_charge_effective_start_date`, `younium_charge_effective_end_date` | Charge dates, falling back to the subscription dates           |
| `younium_start_on`, `younium_end_on`                                       | Whether the charge aligns to the order or uses a specific date |
| `younium_line_item_status`                                                 | `New`, or `Changed` on an amendment                            |

### Company Properties

CPQ writes the Younium account identity back to the deal's company when a quote is sent, accepted, and signed: `younium_account_id`, `younium_account_number`, `younium_legal_entity`, `younium_org_nr`, `younium_tax_reg_nr`, and `younium_invoice_email`.

In the other direction, creating a quote from a deal imports company data onto the quote — invoice email, VAT number, and organisation number from the Younium properties, and the address from either the Younium properties or HubSpot's standard address fields. Creating an amendment from a deal imports the mapped deal and company values onto the new quote in the same way. The import only fills fields that are empty, so it never overwrites what a sales user has already entered. A company name change in HubSpot is synced to CPQ, updating the customer name on that company's quotes that have not yet been converted.

> **Note on property names:** These `younium_*` properties come from Younium's HubSpot schema. CPQ writes to them by name, so renaming or deleting them in HubSpot stops the corresponding data flowing.

Beyond the built-in properties, any `younium_*` deal or company property that matches a CPQ custom field by name is exchanged automatically, which allows an organisation's own fields to flow between the two systems without bespoke configuration. Quote custom fields are exchanged with the deal in both directions, and account custom fields are read from the company. Custom field values are written to HubSpot at the same points as the built-in properties: when a quote is sent, accepted, and signed. If CPQ cannot read the portal's list of properties at that moment, it writes only the built-in properties and leaves custom field values for the next of those events.

### Field Mapping

The properties above are the defaults. An administrator can change which HubSpot property each CPQ field is exchanged with, map a field the defaults leave out, or switch a default off. Each mapping links one CPQ field to one property on the deal or on the company, and runs in one direction — from CPQ to HubSpot, from HubSpot to CPQ, or both — or is off. Resetting a changed mapping restores its default, and moving a field from the deal to the company (or back) switches off the mapping it leaves.

Every quote and customer field in the tables above can be mapped, together with the quote's **Billing frequency**, **Total contract value**, and **Valid until**, and every active quote and account custom field. The Younium order number, order ID, account ID, account number and legal entity are always written by CPQ and cannot be remapped. Billing frequency is written as `monthly`, `quarterly`, `biannual`, `annual`, or `endOfTerm`.

CPQ refuses a mapping that could not work:

| Mapping                                                                                                                                                                            | Why it is refused                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| HubSpot to CPQ into a field CPQ calculates (terms, auto-renewal, remarks, dates, change type, billing frequency, total contract value, valid until, customer name, address line 2) | CPQ owns the value                     |
| CPQ to HubSpot into a property that is read-only or calculated in HubSpot                                                                                                          | HubSpot does not accept the value      |
| A CPQ field and a HubSpot property of incompatible types                                                                                                                           | The value cannot be converted          |
| CPQ to HubSpot into a property CPQ already writes, or that another CPQ field already writes                                                                                        | Two values would overwrite each other  |
| Moving a field onto the deal or company when it already has a mapping there                                                                                                        | The existing mapping is edited instead |

The field mapping list flags a mapping whose HubSpot property no longer exists on the portal, and a mapping to a HubSpot dropdown that lacks some of the values CPQ can send, naming the missing values. A default whose property does not exist on the portal is left out of the list. CPQ holds the portal's list of properties for up to 15 minutes, so a property just created in HubSpot can take that long to become available unless the list is refreshed.

### Field Mapping

Beyond the built-in properties, an administrator can choose which other HubSpot deal and company properties exchange data with CPQ fields. Mappings are managed in the **Field mapping** section of the HubSpot integration settings, which lists the organisation's own mappings and, under **Syncs automatically**, the exchanges CPQ always performs: custom fields matched to a `younium_*` property of the same name, the built-in Younium deal and account properties, and the company address.

Each mapping pairs a HubSpot property with a CPQ field and has a direction:

| Direction         | Behaviour                                                                 |
| ----------------- | ------------------------------------------------------------------------- |
| **HubSpot → CPQ** | Fills empty fields on new quotes from the deal or company                 |
| **HubSpot ← CPQ** | CPQ writes the field to HubSpot when a quote is sent, accepted, or signed |
| **Both ways**     | Fills empty fields on new quotes, then writes back                        |
| **Off**           | Keeps the mapping without exchanging any data                             |

A CPQ field can be a built-in quote or customer field, or a quote, account, product, or charge custom field. The quote terms (initial term, renewal term, auto-renewal, start date, billing frequency, valid until, and remarks), the customer name and address, the organisation number, the VAT number, and the invoice email can all be read from HubSpot. Fields that CPQ itself manages — such as the Younium order and account identifiers, the legal entity, the change date, and the total contract value — can only be written.

**Adding and editing.** **Add mapping** opens a drawer with searchable lists of HubSpot properties and CPQ fields. Options that cannot be used are shown greyed out with the reason:

| Reason shown                      | Why the option cannot be chosen                                               |
| --------------------------------- | ----------------------------------------------------------------------------- |
| **Type doesn’t match**            | The HubSpot property and the CPQ field hold different kinds of value          |
| **Syncs automatically**           | The property is already exchanged by one of the automatic mappings            |
| **Mapped**                        | The CPQ field already has an active mapping to that object                    |
| **Read-only in HubSpot**          | The property is calculated or read-only in HubSpot, so CPQ cannot write to it |
| **Used by** *field*               | Another CPQ field already writes to that property                             |
| **Can’t sync with this property** | The CPQ field can only be written, and the property cannot be written to      |

Editing a mapping lets either side be changed, as well as the direction. Deleting a mapping removes it; if CPQ exchanges that field automatically, the automatic behaviour applies again. **Refresh properties** reloads the property list from HubSpot so newly created properties can be chosen.

**Warnings.** The list can be filtered to **Deal**, **Company**, or **Needs attention**, and searched by field or property name. A mapping needs attention when:

* **Missing** — the HubSpot property no longer exists. The mapping is skipped until it is fixed.
* **Options** — a dropdown field in CPQ has values that the HubSpot property does not offer. CPQ writes the values as they are, so a quote carrying a missing value does not update HubSpot until the option is added there. The drawer shows each CPQ value alongside whether HubSpot has it.

**Pre-filling new quotes.** When a quote is created from a deal, the values read through **HubSpot → CPQ** and **Both ways** mappings pre-fill the new-quote wizard — quote terms, start date, billing frequency, valid until, remarks, customer name, and address. A value that cannot be read as the field's type, such as a term that is not a whole number of months, is ignored and the wizard keeps its default. If HubSpot cannot be read, the quote is created without the mapped values.

### Account Linking

A Younium account is linked to a HubSpot company by the account's `integrationHubspotCompanyId` custom field, falling back to the account's external CRM identifier. When no Younium account can be found, the deal is shown as not linked to Younium and quoting continues against the HubSpot company until conversion creates the account. On conversion, CPQ writes the HubSpot company's id to both fields on the new account and writes the account number back to the HubSpot company. An account created from a quote that has no HubSpot company leaves both fields empty.

Where an organisation invoices a different company than the one on the deal, CPQ can take the invoice account from a HubSpot association: an administrator nominates which deal-to-company association label identifies the invoicing company, and CPQ resolves the bill-to account from the company carrying that association. This requires the company to have its Younium account number populated; otherwise the quote bills the primary account.

### Settings

| Setting                     | Description                                                                                                             | Default                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Connection                  | OAuth connection to a HubSpot portal, scoped to a legal entity                                                          | Not connected                                               |
| Deal amount metric          | Which figure is written to the deal: TCV, CARR, or CMRR. A field mapping to the deal's Amount property takes precedence | CMRR                                                        |
| Deal stage mappings         | Which stage each CPQ event maps to, per pipeline                                                                        | None                                                        |
| Invoice account association | Which deal-to-company association identifies the invoicing company                                                      | None                                                        |
| Field mapping               | Which deal or company property each CPQ field is exchanged with, and in which direction; administrators only            | The Younium properties and name-matched custom fields above |
| Activity log                | Which CPQ events are written back to HubSpot, as an email or a note                                                     | Per event                                                   |
| User mappings               | HubSpot user to CPQ user associations                                                                                   | Email match                                                 |
| Field mapping               | Which further deal and company properties exchange data with CPQ fields, and in which direction                         | Automatic mappings only                                     |

Events available for the activity log are quote sent, viewed, accepted, declined, signed, converted, lost, message sent, signer viewed page, approval submitted, approved, and rejected.

***

## 21. Younium Synchronisation

CPQ holds its own copy of the reference data it needs to quote, kept in step with Younium.

### What Is Synchronised

| Data                         | Notes                                                                            |
| ---------------------------- | -------------------------------------------------------------------------------- |
| **Products**                 | With their charge plans, charges, price details, and custom field values         |
| **Credit types**             | With their default credit terms, prices, and rate cards, where Credits is in use |
| **Accounts**                 | The customers available to quote                                                 |
| **Legal entities**           | The legal entities the user can quote for                                        |
| **Currencies**               | The currency options offered on a quote                                          |
| **Countries**                | Used for addresses and tax identification                                        |
| **Payment terms**            | Offered on accounts and quotes                                                   |
| **Exchange rates**           | Where configured in Younium                                                      |
| **Custom field definitions** | Imported from Younium's field configuration                                      |

Quote contacts are not synced — they are managed in CPQ on the quote itself.

### When It Runs

Synchronisation happens during onboarding, on demand, and in response to Younium events. The onboarding wizard performs the initial sync in dependency order and can be resumed or restarted if it is interrupted. An administrator can afterwards sync any single data set, or everything, from the Younium integration's page under **Settings → Integrations**, and can refresh an individual product or account.

Younium webhooks keep the catalog and accounts current between syncs. CPQ subscribes to product created, updated, and deleted events, and to account created and changed events, updating its copy as they arrive.

### Onboarding Mode

Each legal entity can be placed in **onboarding mode** while it is being set up, so that quotes, products and customers created during testing can be cleared before real selling starts. Younium switches onboarding mode on and off during onboarding; it is not a setting a customer can change. A legal entity is live unless it has been placed in onboarding mode.

While onboarding mode is on, every page in CPQ, including CPQ inside HubSpot, shows a banner saying **Onboarding mode — this workspace isn't live yet.**

**Clearing test data.** While the legal entity is in onboarding mode, Younium can delete its CPQ data on request, in three categories:

| Category      | What is deleted                                                                                                                              |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Quotes**    | Every quote, including change quotes, with its customer quote links, sales rooms, signed documents, and CPQ Agent conversations about quotes |
| **Products**  | The product catalog held in CPQ, with its bundles and product custom field values. All quotes are deleted too                                |
| **Customers** | The customer accounts held in CPQ, with their subscription details. All quotes are deleted too                                               |

Quote numbering can also be reset when quotes are deleted, so the next quote starts again from the first number in the sequence. Products and customers are restored on the next synchronisation from Younium. Clearing applies only to data held in CPQ: orders in Younium, envelopes at the e-signing provider and HubSpot deals are left as they are.

**Going live.** An administrator ends onboarding mode with **Go live** in the banner. Going live asks for confirmation, because it is permanent: onboarding mode is switched off and test data can no longer be cleared. CPQ then confirms the legal entity is live and returns to the quote list. **Go live** is not offered in CPQ inside HubSpot.

### Integration Custom Fields

CPQ creates a small set of its own custom fields in Younium, which it uses to carry quote information onto the resulting orders:

| Field                                   | Entity in Younium    | Type | Purpose                                             |
| --------------------------------------- | -------------------- | ---- | --------------------------------------------------- |
| **CPQ Bundle Code** (`cpq_bundle_code`) | Order product charge | Text | Records the code of the bundle a charge was sold in |

The onboarding wizard creates these fields during the initial sync, as its **Integration Fields** step. Afterwards, the Younium integration settings show whether **Integration custom fields provisioned** is satisfied, and an administrator can create any that are missing with **Create missing fields**. Fields that already exist are left as they are, so the action is safe to repeat.

When a quote is converted to a new subscription or a sales order, each charge sold in a bundle carries its bundle's code in **CPQ Bundle Code**. Charges sold on their own carry no value.

CPQ's own fields are not imported when custom field definitions are synced from Younium, so they never appear as quote custom fields.

> **Note on creating the fields late:** Younium keeps a value only for a field that exists when the order is created. Quotes converted before the integration custom fields were created do not carry a bundle code, and creating the fields later does not add it to those orders.

### Bundles in Younium

Younium has no bundle object, so a converted [product bundle](#product-bundles) arrives as ordinary order products and charges, at the bundle prices. The bundle discount becomes an order discount in Younium that applies to exactly the bundle's charges, even where the same product is also on the order outside the bundle. Bundled charges are marked with the bundle's code as described under [Integration Custom Fields](#integration-custom-fields); charges an amendment adds inside a bundle are marked the same way, and a bundle without a code leaves its charges unmarked. The marking is what lets CPQ [rebuild the bundle on the next amendment](#bundles-on-amendments).

### Charge-Level Discounts on the Younium Order

A converted charge carries its [charge-level discount](#charge-level-discounts) so that Younium bills exactly what the quote shows. Each discounted charge — or each discounted tier of a Volume or Tiered charge — arrives with its list price, the net unit price the quote bills, and the matching discount per unit. A fixed-amount discount is therefore spread across the quantity: €300 off 10 units at €500 arrives as a unit price of €470, and on a Flat charge the amount is taken once. A unit price the seller set on the quote is kept rather than replaced by the catalog list price. Because Younium calculates the order's TCV, CMRR, and CARR from the same prices, those figures match the quote's.

On an amendment, a discount added to or changed on a charge carried over from the subscription is sent as a change to that charge, so the new price applies from the effective change date.

### Ramped Quotes on the Younium Order

When a [ramped quote](#ramp-periods) is converted, CPQ writes the fewest charges that still describe the same contract, so the subscription reads as if it had been built by hand:

| On the quote                                                  | On the Younium order                                                                                                                                                 |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A charge priced the same in every period                      | One charge with no dates of its own, following the subscription exactly as on an unramped quote                                                                      |
| A charge priced the same across several consecutive periods   | One charge covering those periods together. An edge that falls on the subscription's start or end carries no date and follows the subscription.                      |
| A charge whose pricing changes between periods                | One charge per step, each dated to its own stretch of the term, back to back                                                                                         |
| The other recurring charges on a product where a charge steps | Divided at the same dates, so each step's product line carries the product's recurring charges for that stretch. Their price is unchanged from one line to the next. |
| A charge that only starts in a later period                   | Starts on that period's start date, without dividing the product's other charges                                                                                     |
| A one-off charge                                              | Never divided. It carries no end date, and a one-off in a later period starts on that period's start date, so it is billed once, when its period opens.              |
| An order-level discount limited to one or more periods        | A discount dated to those periods. It does not divide a charge whose pricing is otherwise the same.                                                                  |

A charge steps when anything that prices it differs from the period before: its quantity, list or unit price, charge-level discount, tier ladder, usage forecast, price period, billing settings, or unit of measure.

Younium holds each catalog charge once per product line, so a product with a stepping charge appears on the order once per step, each line covering its own stretch of the term. Products where nothing steps convert as a single line.

> **Note on stepped charges in Younium:** A step that ends before the subscription does carries its own end date, and Younium reports a charge with an explicit end date with the change state *Cancelled*. The step remains billable for its stretch of the term; the state describes how the order ends the charge, not a cancellation of what was sold.

### Removals and Deactivation

When a full synchronisation completes, anything no longer present in Younium is retired rather than silently kept. Products absent from the pull are deactivated and hidden from quoting, and the same applies to their charge plans, charges, and prices; charge plans and charges missing from a product's payload are deactivated individually. Accounts absent from the pull are deactivated. A product deleted in Younium is deactivated the same way when the deletion event arrives. Reference data — countries, currencies, payment terms, exchange rates, and legal entities — is removed outright, since these lists have no history to preserve.

Products, charge plans, and charges are also withdrawn from new sales once their end-of-new-sales date is reached, without being deactivated (see [End of Sales](#end-of-sales)).

### Excluding Products from CPQ

A product kept in Younium but not sold through CPQ can be hidden by ticking its **Exclude from CPQ** checkbox in Younium. CPQ creates this product custom field itself: the onboarding wizard adds it before the first product sync, and on an existing connection an administrator adds it with **Create missing fields** in the Younium integration settings, which reports **Integration custom fields provisioned** as unmet until then.

An excluded product is hidden, not deactivated. It disappears from the quote builder's catalog and search, the admin catalog, products offered from HubSpot, and the CPQ Agent's product lookups. Its charge plans, charges, and prices continue to sync, so a subscription that already carries the product can still be amended without that product being cancelled. Clearing the checkbox makes the product available again on the next sync.

> **Note on Younium migrations:** If a Younium environment is migrated and the platform's internal identifiers change, CPQ recognises the catalog by product, charge plan, and charge numbers within the legal entity and re-points its stored references. Existing products, and the quotes built on them, keep working rather than reappearing as duplicates.

### When the Younium Connection Fails

Actions that need Younium — converting a quote in particular — depend on the signed-in user's Younium credentials. If those credentials have been revoked or are no longer valid, CPQ reports the connection as disconnected and prompts the user to reconnect, rather than presenting the problem as a failure of the quote. Conversion errors returned by Younium are surfaced with the platform's own validation detail so the cause is visible.

***

## 22. Users and Roles

CPQ has two roles:

| Role      | Access                                              |
| --------- | --------------------------------------------------- |
| **User**  | Creates and manages quotes                          |
| **Admin** | Full access, including settings and user management |

Users are brought in from Younium. Younium users holding **Sales Admin** or **System administrator** roles become CPQ administrators on import, and an existing standard user is promoted if their Younium role is an administrator one. The first user in a tenant becomes an administrator so the organisation can configure itself. Administrators can browse Younium's users and import the ones who need access.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.younium.com/sales-and-product-led-growth/cpq.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
