270710 Deal Process V2
Date: 2026-07-10 Status: target process and implementation plan; not yet implemented
Objective
Create a simple path from sales to delivery without asking staff to reproduce the proposal structure in CRM.
The first version should work as follows:
- Create a Qwilr page from the Deal.
- Let staff build and edit the commercial proposal directly in Qwilr.
- Retrieve the accepted financial structure from Qwilr.
- Use
Business Categoryto choose the main handoff process. - Prepare a sensible default delivery setup from the accepted one-off and recurring values.
- Let the user confirm the default or customise it before operational records are created.
The default should handle most Deals without requiring staff to understand Accepted Proposal Lines, Delivery Model structure, or downstream record relationships. Delivery Models remain flexible for the cases that need separate tasklists, budgets, or tracking.
The process must support:
- one-off tech projects;
- tech-project retainers;
- MSP agreements with one-off onboarding and recurring service;
- monitoring, support, seats, and licences;
- hardware sales and basic fulfilment;
- Deals containing both one-off and recurring components.
Process At A Glance
| Step | User or event | Result |
|---|---|---|
| Qualify | Sales progresses a Deal | The opportunity moves through the open pipeline |
| Generate | User creates a Qwilr proposal from the Deal | Middleware creates one editable page and stores its Qwilr identity on the Deal |
| Author | Staff build the proposal in Qwilr | Commercial lines, options, quantities, prices, and narrative remain flexible |
| Accept | The client accepts the Qwilr page | Middleware retrieves the accepted quote, calculates the commercial values, and moves the Deal to Reserved |
| Prepare | Middleware applies the Business Category handler |
A default project, Delivery Model, plan, or fulfilment handoff is proposed |
| Confirm | User accepts or customises the handoff | The intended delivery structure is explicit before records are created |
| Create | Middleware applies the confirmed handoff | Downstream records are created idempotently |
The default path is short: generate, author, accept, confirm. Detailed commercial line management in CRM is not part of the first version.
Core Record Responsibilities
| Record | Responsibility |
|---|---|
| Deal | Opportunity, Business Category, Qwilr association, accepted values, sales outcome, and handoff status |
| Qwilr page | Proposal authoring, commercial presentation, client choices, and acceptance |
| Accepted Proposal Line | System-held snapshot of an accepted Qwilr line; not a proposal-entry interface for staff |
| Project / tasklist | One-off delivery, onboarding, hardware fulfilment, and time capture |
| Delivery Model | Revenue and labour budget for a defined delivery scope |
| Managed Services Plan | Ongoing MSP service, billing rules, seats, licences, monitoring, and recurring resource budgets |
| MSP Invoice Line | Effective-dated recurring charge belonging to a Managed Services Plan |
| CRM / Xero invoice | Amount due and payment state |
The Deal remains the historical commercial record. It does not become the source of truth for project progress, recurring-service status, invoice payment, or offboarding.
Deal Pipeline
Open Sales Stages
The open pipeline remains:
Limbo/Follow Up;Connection Made;Proposal;Stretch For Month.
Terminal Sales Outcomes
The sales process ends at:
Reserved: accepted and commercially won, with 100% probability andClosed Won/Closedclassification;Closed Lost: not proceeding, with 0% probability andClosed Lost/Omittedclassification.
Final Qwilr acceptance moves the Deal to Reserved and establishes that it is
won. The operational handoff can remain at Awaiting Confirmation without
keeping the Deal in the open sales pipeline. Payment, delivery, recurring
service, and offboarding do not change whether the Deal was won.
Temporary Post-Win Stages
The existing post-win stages may remain as temporary Kanban labels:
Hardware Paid;Paid 50%;Paid 100%;Recurring Monthly Support;Recurring Monthly Project;Microsoft Licenses;Won;CREDIT HOLD - Unpaid;Home Support (T-Club);Be Connected;Offboarded.
They are optional display categories, not workflow states. Moving a Deal to one of them must not create or modify delivery, plan, or invoice records. They can remain until structured CRM and Power BI views replace the current Kanban.
Proposal Capability Stages
Stage 1: Flexible Qwilr Authoring
Stage 1 treats Qwilr as the proposal-authoring surface.
- Middleware creates an editable Qwilr page from the Deal and selected template.
- The page carries the Deal ID and creation request ID in page metadata.
- Staff add, remove, and edit Quote Block lines and Plan Cards in Qwilr.
- Staff do not create matching Deal Lines or Products in CRM first.
- On acceptance, middleware stores the accepted selections and calculates the one-off and recurring values.
Business Categorychooses the default handoff.- The user confirms the default or opens a custom handoff editor.
Stage 1 deliberately does not try to infer detailed product meaning from every Qwilr line. Editor-created accepted pages reliably provide selected state, quantity, unit price, billing schedule, and aggregate values, but line names, discount allocation, Product IDs, and routing metadata may be unavailable.
This is sufficient to calculate the commercial shape and prepare a useful default. It is not sufficient to distinguish every licence, audit, onboarding activity, or support component automatically.
Stage 2: Structured Proposal Components
Stage 2 adds an optional structured authoring path for repeatable offerings. It does not remove Stage 1.
Staff select proposal components through a lightweight CRM interface rather than the standard Deal Product Lines experience. Example actions may include:
- add MSP package;
- add onboarding;
- add audit;
- add recurring support or retainer;
- add licence;
- add hardware;
- add custom component.
Middleware generates the Qwilr Quote Blocks and Plan Cards from those components. Each generated section or line carries a stable component ID and routing metadata, for example:
{
"componentId": "<crm-component-id>",
"chargeType": "one_off",
"route": "msp_onboarding",
"deliveryGroup": "onboarding"
}
Qwilr remains the presentation and acceptance interface. The additional metadata allows the accepted handoff to determine:
- the exact component selected;
- its invoice description and account mapping;
- whether it belongs to a Project or Managed Services Plan;
- whether it creates a Delivery Model or a charge only;
- which tasklist or Delivery Model group it belongs to;
- which labour and resource defaults apply.
Lines added freely in Qwilr without metadata still enter the Stage 1 confirmation path. A Deal can therefore use either mode without creating a second acceptance or fulfilment process.
Automated Qwilr Creation
The Deal provides one action such as Generate Qwilr Proposal. It calls
Peppermint middleware, which creates the page through the Qwilr API.
Pre-Creation Validation
For Stage 1, middleware validates only what is required to create and associate the page:
- Deal ID and name;
- Company and primary Contact;
- owner and currency;
Business Category;- selected Qwilr template;
- proposal version.
Stage 2 additionally validates the structured proposal components and their stable identifiers.
Validation failures return a clear checklist and do not call Qwilr.
Creation Flow
- Allocate a unique creation request ID for the Deal and proposal version.
- Lock the request so repeated clicks cannot create multiple pages.
- If the request already has a Qwilr page ID, return the existing draft.
- Create the selected template as an editable Qwilr draft.
- Include page metadata identifying the source Deal and creation request:
{
"sourceSystem": "zoho",
"sourceModule": "Deals",
"dealId": "<zoho-deal-id>",
"proposalVersion": "<version>",
"creationRequestId": "<peppermint-request-id>"
}
- For Stage 2, also generate quote sections and lines with component metadata.
- Save the returned Qwilr page ID, status, editor link, public link, PDF link, owner, and template version on the Deal.
- Present the editor link to the user.
Only non-sensitive identifiers belong in metadata. Contact information and commercial values remain in the protected CRM and Qwilr records.
The standard Qwilr-Zoho creation action should be hidden or clearly separated from the V2 action. A page created outside V2 cannot enter the automated handoff until an authorised user registers its page ID against exactly one Deal.
Qwilr Signals
| Qwilr event | CRM action |
|---|---|
| Page published | Save publication time and move an earlier open Deal to Proposal |
| First viewed | Save first-view time; do not change the commercial outcome |
| Partially accepted | Save the signal and notify the owner; do not create fulfilment records |
| Fully accepted | Fetch the accepted page and prepare the handoff |
Repeated views update activity history without repeatedly changing Deal state.
Accepted Commercial Snapshot
On final acceptance, middleware:
- Records the webhook using Qwilr's event or idempotency identifier.
- Fetches the accepted page with page metadata and accepted quote data.
- Requires the Qwilr page ID and metadata to match one stored Deal creation record.
- Confirms the page is fully accepted rather than previewed or partially accepted.
- Saves the acceptance time, signer details needed for audit, Qwilr totals, links, and a protected raw or sanitised response snapshot.
- Stores selected quote sections and lines as protected Accepted Proposal Lines.
- Ignores unselected alternatives for fulfilment and invoicing.
- Calculates the accepted one-off and recurring values.
- Moves the Deal to
Reserved, sets probability to 100%, and uses the acceptance date as the closing date. - Sets
Handoff StatustoAwaiting Confirmationand prepares the default handler for the Deal'sBusiness Category.
Accepted Proposal Lines support calculations, audit history, and later structured automation. Staff do not use them to author the proposal and do not need to classify each line during Stage 1.
Financial Values
Store separate values on the Deal:
One-Off Value;Monthly Recurring Value;Annual Recurring Value;First-Year Value;Accepted Total Due Nowwhere Qwilr supplies it;Accepted At.
Do not treat Qwilr's top-level accepted amount as the value of the complete
contract. A mixed proposal may return the discounted one-off amount there
while recurring charges remain represented by the selected monthly or annual
lines.
Stage 1 uses the accepted aggregate one-off amount after discounts wherever Qwilr supplies it. It calculates recurring totals from the selected billing schedules. If discounts or an unusual schedule cannot be reconciled, the handoff remains awaiting confirmation with a warning.
Default Handoff And Confirmation
The system presents a compact confirmation rather than a line-by-line setup screen. It shows:
Business Category;- accepted one-off, monthly recurring, annual recurring, and first-year values;
- the default Project, tasklist, Delivery Model, or Managed Services Plan action;
- any values that could not be reconciled;
Confirm DefaultandCustomiseactions.
Confirm Default
The default groups work into the smallest useful structure:
- one general tasklist for one-off delivery;
- one one-off Delivery Model using the accepted one-off revenue amount;
- one Managed Services Plan handoff for MSP recurring values; or
- one recurring Delivery Model for a Tech Project retainer.
Category configuration supplies the default names, destination Project, labour assumptions, and responsible owner. Staff do not need to touch the Accepted Proposal Lines or Delivery Model structure.
Customise
The custom path can:
- split the one-off amount across multiple tasklists and Delivery Models;
- separate audit, onboarding, implementation, or other delivery scopes;
- change the Project or tasklist destination;
- change labour quantities, units, dates, and owners;
- treat a recurring Tech Project amount as a finite payment schedule instead of a retainer;
- identify which MSP recurring components create resource budgets;
- exclude licences or pass-through charges from time-based Delivery Models;
- hold selected actions for manual setup.
The custom handoff must reconcile back to the accepted one-off and recurring values. It changes delivery structure, not the signed commercial snapshot.
Business Category Handlers
Business Category is the primary handler selector. The accepted Qwilr
frequencies provide the financial shape, and the user confirmation supplies
the final operational interpretation.
| Business Category | One-off default | Recurring default |
|---|---|---|
MSP |
One onboarding Project/tasklist and one one-off Delivery Model using the accepted one-off amount | Send recurring values to the Managed Services Plan confirmation; do not create a generic recurring Delivery Model from the Deal |
Tech Projects |
One delivery Project/tasklist and one one-off Delivery Model using the accepted one-off amount | Treat recurring value as a retainer and use the current recurring Delivery Model approach, unless the user changes it to a finite payment schedule |
Hardware |
Create basic fulfilment and invoicing; create a Delivery Model only when delivery labour is required | Send to review or an explicit MSP/licence path rather than assuming a time budget |
| Other / mixed | Apply the category's configured default | Require confirmation for unsupported recurring treatment |
This category-led default is intentionally broad. Stage 2 metadata can later override it component by component.
Delivery Models
One-Off Default
For a delivery-bearing MSP or Tech Project Deal with an accepted one-off amount:
- Create or reuse the intended Project.
- Create one category-default tasklist.
- Create one draft Delivery Model with revenue equal to the accepted one-off value.
- Apply the category's default labour and date assumptions.
- Link the Deal, Project, tasklist, and Delivery Model.
This is the 80% path. It remains useful even when the Qwilr API cannot identify whether individual one-off lines are audit, onboarding, or another activity.
If separate tracking is valuable, the user selects Customise and allocates
the same accepted amount across additional tasklists and Delivery Models.
Tech Project Retainer
For Tech Projects, an accepted recurring value normally represents an
ongoing retainer. The default uses the existing recurring Delivery Model
approach and creates the recurring budget against the appropriate Project.
The user can instead mark it as a finite instalment schedule. A project paid monthly does not become a retainer when the work has a defined outcome and end date.
MSP Recurring Values
For MSP, accepted recurring values belong first to the Managed Services Plan.
They do not automatically become Delivery Models.
The plan confirmation determines whether each recurring amount represents:
- support or monitoring that needs a resource budget;
- an included-hours allowance;
- per-seat or per-device service;
- a licence or pass-through charge with no time budget;
- a fixed base charge;
- usage-based support.
Only the components that represent delivery resources create plan-owned recurring Delivery Models. Licences and other charges can create MSP Invoice Lines without creating time budgets.
Confirmed Delivery Models are not silently recalculated if the commercial record later changes.
Managed Services Plan Handoff
Use one active Managed Services Plan per Company as the normal model. The confirmation creates a plan when none exists or updates the current active plan.
The plan owns:
- service model and status;
- start, billing, renewal, and end dates;
- monitoring, support, licence, and included-service components;
- fixed, per-seat, per-device, annual, and usage-based charging rules;
- recurring resource budgets and Delivery Models;
- linked seats and recurring invoice lines;
- support workspace or recurring operational tasks.
An MSP Deal therefore produces two distinct outcomes:
- Initial delivery: the accepted one-off amount becomes the default onboarding Project/tasklist and one-off Delivery Model.
- Ongoing service: the accepted recurring amount enters the Managed Services Plan confirmation and is separated into plan charges and resource budgets.
Onboarding completion does not close or remove the plan. Plan activation uses the agreed service start date and any required readiness check rather than the Deal Stage.
Hardware
Hardware handling remains deliberately lightweight. The Stage 1 default:
- Records the accepted one-off amount and Qwilr link.
- Creates a fulfilment task or lightweight Project with an owner and due date.
- Creates or prepares the hardware invoice draft.
- Tracks ordered, received, configured, delivered, and completed status on the fulfilment record.
- Creates a Delivery Model only when the confirmation includes installation or configuration labour.
Stage 1 may not have reliable item names or quantities for detailed purchasing, so those remain part of the confirmation or manual fulfilment process. Stage 2 can later provide exact hardware components and metadata.
Supplier purchasing, warehouse stock, serial-number management, and device asset registration remain outside this version.
Invoicing
The accepted commercial values and confirmed handler determine invoice setup.
The handoff may create or prepare:
- one aggregate one-off project or onboarding invoice draft;
- hardware invoice drafts;
- deposits or supported instalments;
- effective-dated MSP Invoice Lines for confirmed recurring plan components;
- retainer invoice lines for Tech Projects.
Stage 1 does not guess invoice descriptions or component allocations that are missing from the Qwilr acceptance payload. Those remain part of confirmation. Stage 2 can create exact invoice lines from structured component metadata.
Middleware may create CRM and Xero drafts, but it does not approve or send them. Unsupported payment schedules create a review task rather than guessed invoices.
Invoice payment status remains in CRM/Xero. It may feed dashboards or a temporary FYI Deal stage, but it does not rerun the commercial handoff.
Confirmed Operational Handoff
After confirmation:
- Lock the confirmed handoff version.
- Set
Handoff StatustoProcessing. - Create or update each confirmed Project, tasklist, Delivery Model, Managed Services Plan, fulfilment record, and invoice draft idempotently.
- Store every downstream record link against the Deal and handoff action.
- Set the handoff to
Readywhen every required action succeeds. - Set it to
Needs Reviewwith a precise checklist when required work remains.
The Deal remains commercially won if operational setup needs review. Moving a
Deal back to Reserved is not a retry mechanism. Retries operate through the
recorded handoff and create only missing work.
Required Deal Controls
Recommended V2 fields include:
Qwilr Creation Status:Not Started,Creating,Draft Ready,Failed, orSuperseded;- Qwilr creation request ID, proposal version, page ID, template version, status, owner, and page links;
Qwilr Published At,First Viewed At,Partially Accepted At, andAccepted At;Handoff Status:Not Started,Awaiting Confirmation,Processing,Needs Review, orReady;- one-off, monthly recurring, annual recurring, first-year, and due-now values;
- confirmed handler and handoff version;
- links to the Project, Delivery Models, Managed Services Plan, fulfilment record, and invoices;
- last automation error, review reason, and retry information.
Automated Qwilr creation is metered. The creation request and page ID must be recorded so duplicate clicks, retries, and replacement versions are visible and controlled.
Exceptions And Safe Failure
Keep the handoff at Awaiting Confirmation or move it to Needs Review when:
- a creation request times out and the resulting page cannot be reconciled;
- the Qwilr page ID or metadata does not match the stored Deal association;
- a page created outside V2 has not been explicitly registered;
- selected one-off or recurring values cannot be reconciled to Qwilr totals;
- discounts or payment schedules cannot be interpreted safely;
Business Categoryhas no configured handler;- a Tech Project recurring amount could be a retainer or a finite instalment;
- more than one active Managed Services Plan could be updated;
- a required destination Project or owner is ambiguous;
- a required downstream write fails after other records were created.
Missing Stage 1 line descriptions, Product IDs, or routing metadata are not by themselves failures. The category default handles them at aggregate level. They become review items only when the default cannot safely represent the Deal.
Retries use stable keys derived from the Deal, proposal version, handoff version, purpose, and billing period. They reuse existing records and fill only missing work.
Dashboard Transition
The existing Deal Kanban remains available during rollout, but structured records become the reporting sources:
- sales pipeline and won/lost outcome: Deal;
- proposal activity and acceptance: Qwilr fields on the Deal;
- accepted financial shape: Deal one-off and recurring values;
- delivery and budget: Project, tasklists, and Delivery Models;
- recurring service: Managed Services Plan and MSP Invoice Lines;
- billing and payment: CRM invoices and Xero;
- fulfilment: hardware or onboarding tasks;
- exceptions:
Handoff Statusand review queues.
CRM views and Power BI should progressively combine these records into the whole-business dashboard currently approximated by post-win Deal stages. The FYI stages can be retired once the replacement views cover active work, recurring service, invoicing, credit hold, and offboarding.
Implementation Sequence
Phase 0: Prove API-Created Qwilr Behaviour
Use a disposable Deal and intended templates to:
- Create one Qwilr draft with Deal and creation metadata.
- Confirm ownership, editor access, and stored links.
- Add and edit one-off, monthly, Plan Card, optional, quantity, discount, and tax examples directly in Qwilr.
- Capture publication, view, partial-acceptance, and full-acceptance events.
- Fetch the accepted quote and confirm selected state, quantities, prices, billing schedules, totals, and metadata behaviour.
- Confirm how Qwilr reports mixed one-off and recurring discounts.
- Test whether Stage 2 section and line metadata survives normal Qwilr edits.
- Replay creation and acceptance requests to confirm duplicate-page and duplicate-handoff protection.
Exit condition: one API-created proposal can be associated, freely edited, accepted, fetched, and replayed safely.
Phase 1: Flexible Qwilr And Commercial Snapshot
- Add the V2 generation action and minimal pre-creation validation.
- Create editable Qwilr drafts and store all identifiers and links.
- Reuse the existing draft for repeated user actions.
- Hide or separate the standard Qwilr-Zoho creation action.
- Receive Qwilr events idempotently.
- Calculate and store the one-off and recurring Deal values.
- Store Accepted Proposal Lines as protected system records.
- Prepare, but do not yet execute, the category default handoff.
Exit condition: staff can author freely in Qwilr, and an accepted proposal produces a correct financial summary and default handoff for the correct Deal.
Phase 2: Category Defaults And Confirmation
- Add the compact
Confirm Default/Customiseexperience. - Configure MSP, Tech Project, and Hardware handlers.
- Create the one-off category-default tasklist and Delivery Model.
- Route MSP recurring values to Managed Services Plan confirmation.
- Route Tech Project recurring values to the existing retainer model.
- Support custom Delivery Model and tasklist splits.
- Execute confirmed handoffs idempotently; acceptance has already moved the
Deal to
Reserved.
Exit condition: most accepted Deals require only one confirmation, while special Deals can use the full Delivery Model flexibility.
Phase 3: MSP, Invoicing, And Hardware Completion
- Create or update one active Managed Services Plan per Company.
- Separate plan charges from resource-bearing recurring components.
- Create plan-owned recurring Delivery Models only where required.
- Create effective-dated MSP Invoice Lines.
- Create supported one-off, retainer, hardware, and onboarding invoice drafts.
- Complete the basic hardware fulfilment path.
Exit condition: MSP, recurring Tech Project, and hardware Deals create their confirmed operational records without reconstructing the proposal.
Phase 4: Structured Proposal Alternative
- Add the lightweight Proposal Components interface.
- Define reusable MSP, onboarding, audit, support, licence, hardware, and custom components.
- Generate Qwilr quote sections and lines with stable metadata.
- Route accepted structured components to exact tasklists, Delivery Models, plan components, and invoice lines.
- Keep metadata-free Qwilr additions on the Stage 1 confirmation path.
Exit condition: repeatable offerings can use precise component automation without removing the flexible Qwilr-first workflow.
Phase 5: Reporting And Legacy Retirement
- Build CRM views and Power BI reporting from the structured records.
- Remove core automation dependencies on Deal-created Delivery Models and post-win Stage changes.
- Migrate only active legacy records needed for operations or reporting.
- Retire FYI Deal stages when replacement dashboard coverage is sufficient.
Exit condition: the post-win Kanban is optional rather than operationally necessary.
Acceptance Criteria
Stage 1
- A user generates an editable Qwilr draft from a Deal without creating CRM proposal lines first.
- Repeated clicks and retries do not create duplicate chargeable pages.
- Staff can add and edit Quote Block lines and Plan Cards directly in Qwilr.
- A fully accepted page produces separate one-off and recurring Deal values.
- A fully accepted page moves the correct Deal to
Reservedonce, even while its operational handoff awaits confirmation. - Unselected alternatives create no fulfilment or invoices.
- Accepted Proposal Lines are retained without becoming a required user interface.
Business Categoryselects the default handler.- An MSP one-off value prepares one default onboarding Delivery Model.
- MSP recurring values go to Managed Services Plan confirmation rather than automatically becoming time budgets.
- Licences can become plan charges without creating Delivery Models.
- A Tech Project one-off value prepares one default project Delivery Model.
- A Tech Project recurring value defaults to the current retainer model.
- A user can confirm the default without editing its structure.
- A user can instead split work across tasklists and Delivery Models.
- A confirmed operational handoff runs once.
Stage 2
- Structured proposal components generate Qwilr sections and lines with stable external metadata.
- Accepted metadata identifies exact delivery, plan, and invoice routing.
- Metadata-free Qwilr additions remain visible and require confirmation rather than being discarded.
- Stage 1 and Stage 2 use the same accepted snapshot, confirmation, Reserved, and idempotent handoff process.
General
- Partial acceptance creates no operational records.
- Automation creates Xero drafts but never approves or sends them.
- Replayed events reuse existing downstream records.
- Later post-win Deal Stage changes do not rerun the handoff.
- Every unsupported or ambiguous action is preserved with a precise review reason.
Parameters To Confirm During Build
- Category-default Project destinations, tasklist names, labour assumptions, dates, and owners.
- Whether accepted Qwilr values populate the existing
AmountandACVfields or only the new explicit one-off and recurring fields. - The boundary between an automatically prepared handoff and the required user confirmation.
- The rules that distinguish a Tech Project retainer from a finite instalment.
- The Managed Services Plan confirmation experience for licences, seats, monitoring, support, and usage charges.
- Supported automatic invoice and payment-schedule patterns.
- The first structured Proposal Components offered in Stage 2.
- Roles allowed to confirm handoffs, edit delivery allocations, and register exceptional Qwilr pages.
- PAYG or prepaid Qwilr credit handling and the owner of usage monitoring.
- Which temporary post-win stages remain manually maintained during the dashboard transition.
Deliberate Limits
This version does not automate:
- supplier purchasing or warehouse stock;
- detailed device and serial-number asset management;
- Xero invoice approval, sending, payment chasing, or credit notes;
- detailed revenue recognition;
- full historical migration;
- every unusual Qwilr payment structure;
- immediate removal of the existing post-win Kanban.
The standard Qwilr-Zoho related list may remain visible to users, but it is not an integration source. The production association is the metadata supplied during API creation and the matching Qwilr page ID stored against the Deal.
See 270710 QWILR Options Research for the supporting API tests and constraints.