I'm implementing it · 10 min read
Decide before you configure
The decision is made, or nearly, and you need the order things go in and what to sign before anyone configures anything.
If you have five minutes
- Seven decisions with named owners, signed before configuration. The first is which system is the receivables ledger of record. The signed memo is also the artifact that carries the CFO's buy-in.
- Term of record and billing migration are two different projects that share a name. The first is reversible and has no parallel run. The second is set per contract at creation, never changed, and needs one full billing cycle and one period close before cutover.
- Product library first, then contract structure, then billing schedule, then quote rules, then the reporting spec. Six records carry one sale; know which number on each you can trust.
- The stage nobody scopes is the one right after the customer says yes. Decide what event acceptance actually is — five departments usually hold five different unstated answers — then build the fan-out: who is told, when, and with which fields.
Decide before you configure
The intuitive order is discover, build, train, test, get buy-in. For a system that issues financial documents that order is wrong three ways: buy-in happens at different moments for different people, testing cannot be a single phase, and the people who catch errors have to be trained before the people who create volume. So the engagement starts with a signed set of decisions, each with a named owner.
Show: Seven decisions, signed before configuration| Decision | Owner | What it costs to get it late |
|---|---|---|
| Which system is the receivables ledger of record | CFO or controller | Two ledgers and a reconciliation that grows monthly |
| Where HubSpot stops and recognition begins | Controller | Audit exposure and lost credibility |
| Commission on bookings, billings or collections | Sales leadership with finance | A comp dispute at go-live |
| What constitutes one contract | Finance with RevOps | Every downstream report wrong; not editable after create |
| Who may create products and price books | RevOps | Catalog sprawl within a quarter |
| Who authorises credit memos and refunds | Controller | An audit finding |
| What lands on unshipped capability, and what happens to it | RevOps with whoever owns the outcome | A workaround built into the foundation that has to be unwound |
The chain, object by object
Six records carry one sale from the quote to the cash. Each one has a job, and the reporting mistakes come from asking one of them a question that belongs to another.
Show: The contract is the agreement ledger; the orders are the event ledger| Object | What it is for | The number on it you can trust |
|---|---|---|
| Deal | The sales process. It ends when the customer commits | Four rollups computed from the line items. The headline amount is a number someone typed |
| Quote | The offer, and where the contract's clock starts | Total contract value on the quote; the headline switches between contract value and first payment depending on a setting |
| Contract | The agreement: committed revenue, term, renewal, every change since. Locks at creation | Committed value, recurring revenue, the change history. This is the bookings ledger |
| Order | The event. On every accepted change HubSpot creates one carrying the difference | Its total is typed, not computed. Read the order as an event, not a total |
| Invoice | The billing document, immutable once issued. Corrected by credit memo or void | Its subtotal is a real sum of its own line items, for one billing period |
| Payment | The cash event | What actually landed, and when |
| Subscription | Recurring billing execution, running under the contract | Total recurring revenue as a rollup; check what is associated before trusting it |
Six properties nobody sees and everyone lives with
- Billing enabled, set at birth
- Whether HubSpot bills a contract is decided when the contract is created and cannot be changed afterward. Term of record or billing migration is a create-time choice, not a switch you flip later.
- The effective date, immutable
- Decided on the quote, arrives on the contract, never moves. A wrong convention means reloading the agreements. Billing start and recognition start can legitimately differ from it, which is a design choice the platform supports, not a workaround.
- Term as a number of payments
- A three-year agreement is thirty-six monthly or three annual payments on the recurring line. A text field on a deal saying three years drives nothing and will disagree with the line within a quarter. A line left to renew automatically with no count is evergreen, and it never reaches completed on its own.
- The annual figure caps at twelve months
- Annual recurring revenue on a line is the monthly figure times the term, capped at twelve. A six-month contract reports six months of it, not an annualised run rate; a three-year contract reports twelve while total contract value keeps counting.
- One line item, many copies
- A line item is copied at every hop, the quote, the subscription, each invoice, each payment, except one: the deal and the order share the same record. Sum the object without a filter and one ordinary six-month sale counts two and a half times. Report on the container's rollup, never the raw line items.
- Percentage discounts only, on a contract line
- A contract line accepts a percentage off list and refuses a flat amount. Concessions are negotiated in dollars, so you convert. It reads as an annoyance and it is a position: the discount is stored as a relationship to list, so it can be reported and rolled off at renewal.
One honest gap
The contract object carries over a hundred native properties and the public write path to it is still a beta. Everything above comes from HubSpot's documentation, a production migration and a validated live run, not from a property-by-property audit. Where a claim matters to your build, read your own portal's schema before you rely on it.
The eleven stages, and the three nobody scopes
Everything above is the order the engagement runs in. This is the order the business runs in, and they are two different documents for two different rooms. Eleven stages carry a thing you sell from the catalog to the cash and back out again at renewal.
Show: The first three are what every HubSpot implementation already covers well, because they are the three the product demo shows| Stage | Starts when | Whose it is |
|---|---|---|
| Catalog | A thing becomes sellable | RevOps |
| Configure | A buyer wants a specific version of it | Sales |
| Quote | The configuration becomes an offer | Sales, with approvers |
| Accept | The buyer says yes | Nobody, in most businesses |
| Commit | The agreement becomes a record | Finance with RevOps |
| Fulfil | The customer gets what they bought | Delivery or operations |
| Bill | A billing date arrives | Accounts receivable |
| Collect | The invoice is due | Accounts receivable |
| Change | The agreement changes mid-term | Sales or customer success |
| Renew or end | The term runs out | Customer success |
| Report | Continuously | Finance |
Three numbers run beside all of it and they belong to three different people: bookings, which sales leadership owns and which moves when the customer commits; billings, which the controller owns and which moves when an invoice is issued; and revenue recognised, which the controller also owns and which moves on its own schedule. They are supposed to disagree with each other. A business that has never separated them does not have one number, it has one number that is wrong in three different ways.
What happens when they say yes
This is the stage worth spending the most time on and the one almost nobody designs. What transfers today, in most businesses, is a status change and a PDF. The terms stay in prose. Finance experiences that as finding out a deal closed when the customer rings asking for an invoice; the person who sold it experiences the same event as being asked a lot of questions about a deal they have already closed. It is one of only two moments in the whole span that both sides feel from opposite ends, which is what makes it worth fixing first.
Before any of the wiring, there is a question that sounds procedural and is not: what event actually is acceptance? There are at least five candidates, and a business usually holds a different unstated answer per department.
Show: Until one of these is chosen and written down, every notification downstream fires at a different time from every other, and nobody can say whether the process is late — because there is no agreed moment it was supposed to start from| The candidate | Who treats this as the moment |
|---|---|
| The buyer signs the quote | Sales — it is the commission moment |
| The business countersigns | Legal |
| The contract record is created | Finance |
| A deposit or first payment clears | Accounts receivable, in deposit-gated businesses |
| The kickoff is scheduled | Delivery |
Then the fan-out, which is the actual deliverable of this stage. Build this table with the business, in their own org, and treat every empty cell as a finding rather than a gap to fill in later.
Show: The last row is the one that gets left out, and it is the most common avoidable cause of a disputed first invoice| Who | When | What they actually need | If they do not get it |
|---|---|---|---|
| Accounts receivable | At acceptance, before the first bill date | Contract, billing schedule, first invoice date, billing contact, purchase order number, tax treatment, payment terms, whether a deposit is owed | Invoices late or wrong, and the customer finds the error first |
| Delivery or professional services | At acceptance | What was sold as a quantity rather than a name, the start date, the scope boundary, the customer's contact, any dependency the sale assumed | Provisions the wrong amount, or does not start at all |
| Provisioning or warehouse | At acceptance, or at payment if there is a deposit rule | Stock keeping unit, quantity, ship-to, required-by date | Stock committed against nothing, or a shipment nobody billed |
| Customer success | At acceptance | Term, renewal date, entitlements, what was promised verbally, who owns the relationship now | The renewal gets discovered from a calendar reminder |
| Sales operations and commission | At acceptance | The booking, against whichever basis was agreed: bookings, billings or collections | A commission dispute at the worst possible moment |
| Legal | At execution | The executed document, where it is retained, which terms govern | No retrievable record on the day it matters |
| Finance leadership | At period close | The bookings movement and the recognition treatment | Forecast and actuals diverge with no available explanation |
| The customer | At acceptance, the same day | Confirmation, what happens next, who their contact is, when and how they will be billed | The first invoice is the next contact they have from you |
- Send the fields, not the document
- A PDF is a notification, not a transfer. If the person receiving it has to open an attachment and re-key what is inside, the seam has not been closed, it has been decorated. The records are workflow-enrollable the moment they are created, which is what makes a real fan-out possible: each function gets a payload in its own shape, built from the connected records.
- The payload is only as good as the catalog
- Delivery needs quantity as a number. The person in accounts payable needs a product name a stranger can verify. Both of those were decided months earlier, in the product library, by somebody who was not thinking about either of them. That is why the catalog comes first in the design order above and not because it is the easy part.
The decisions this stage forces are worth writing into the same signed memo as the seven at the top: what event is acceptance, who owns the customer afterward and from what moment, whether fulfilment starts before payment clears, whether the fulfilment instruction is the contract's own line items or a separate work order, and which of the notifications above are blocking rather than informational. None of those is a configuration question, and none of them has a default worth accepting.
The order the design goes in
- Product library and price books first. Everything downstream inherits it, and the pricing model per product is the hardest thing in the build to reverse.
- Contract structure: grain, term handling, renewal treatment, what a change looks like.
- Billing schedule design, only if HubSpot bills: dates, frequencies, consolidation, staggered terms.
- Quote templates, rules and approvals last, because the thresholds depend on the product structure.
- The reporting spec, written before the build. It is the top of the derivation chain and it is how you verify the build was right.
Five things a real migration taught me
From moving about four hundred agreements onto the contract record in a production portal. Two of these contradict HubSpot's own migration guide.
- Reading contracts is not writing them. Prove the write path with one throwaway record before building a pipeline. Bulk import runs through the interface, by a person with a Revenue Hub seat.
- One contract per agreement, and take the term from the original deal, not the subscription. A chain of annual subscriptions is one agreement plus renewals, not three agreements.
- The import wants the contract's fields on every line-item row, not the first row only. The guide says otherwise; the importer does not agree.
- A failed import burns its unique id. Retrying with the same id fails as "already exists" on an empty portal. Fresh id every attempt, and a ledger of attempts.
- Import line items as custom lines. Hydrating them from products fails even when the product exists.
Check your own portal first
Before any of this, nine questions tell you whether the agreement record can even represent your book: evergreen terms, chained multi-years, one-time lines that will need changing, whose ledger the money lives in. It runs in the browser, nothing is captured, and the result is yours.
Where to next
The nine-question read
Whether the agreement record can represent your book at all.
How I run a contracts engagement
The engagement shape behind this page.
The Line Item Series
Eight pieces tracing one sale to fifteen records, and the 2.5x that follows from summing them.
Which one is you
The four archetypes, for the whiteboard.
Where this comes from
- Ryan's order of operations and engagement plan. phases 0 to 9, the decision gate, the two modes; authored 2026-08-16 and 2026-08-29
- HubSpot's Contracts API, 2026-09 beta, and Quotes API, 2026-03. immutable fields, change types, the effective-date bridge; read 2026-08-23
- A production migration of about four hundred agreements, August 2026. the five traps and the two places HubSpot's own guide is wrong; anonymised
- The Line Item Series, published 2026-09-05. research read against a live portal 2026-08-02 and adversarially verified; one sale, fifteen line items, the rollups that are real and the one that is typed
- A validated live run, 2026-08-23. a buyer-initiated change quote accepted end to end; the platform minted the order and voided the stale invoice
- The Sales-to-Finance handoff analysis, 2026-08-16. the six seams; close-to-notification and mid-contract change are the two both sides feel from opposite ends, which is why the acceptance section leads with them
What we do not know yet
- The Contract object carries over a hundred native properties and has not been audited property by property; every claim here traces to documentation, a migration or a live run, not to a full schema read.
- The Contracts API is a beta that already moved an endpoint once mid-flight. Anything built on it pins the doc revision it was built against.
- Whether every path that creates an order reuses the deal's line item the same way has been observed on eight cases, all through two creation paths.
- The fan-out table is a design, not a measurement. Finance has never spoken directly in the 794 conversations this material was built from — it appears only in the third person — so what a controller actually needs at acceptance is being measured, not assumed.
Mid-way through a quote-to-cash build, or stuck on one?
Come walk through it on the show and we will work it out on air, weekday mornings.