Copy page

Sell and get paid

Quotes

A quote is a priced proposal you send a customer to sign. When they sign it, Kontier provisions what was agreed: the subscription is created from the quote, at the prices on the quote.

That last part is the whole point. Without it, somebody reads a signed PDF and retypes it into the billing system, and the bill quietly stops matching the contract. A quote is the contract and the instruction.

A negotiated deal carries two things a catalog price does not: how long the agreed prices hold, and whether they change while they hold. A quote states both. When it is signed, they become an agreement on the subscription, which is the record of what was promised and until when.

✕

Three kinds

kind is required and cannot change afterwards.

Kind	Use it for
NEW_SUBSCRIPTION	A new customer, or a new subscription for an existing one
SUBSCRIPTION_UPDATE	Changing an existing subscription: more seats, a different plan
ONE_OFF	A one-time charge with no subscription behind it

The lifecycle

Ten states. Most quotes touch four of them.

Code
DRAFT ──▶ PENDING_APPROVAL ──▶ APPROVED ──▶ SENT ──▶ VIEWED ──▶ SIGNED
   ▲             │                            │
   └── CHANGE_REQUESTED                       ├──▶ DECLINED
                                              ├──▶ EXPIRED ──▶ (revise)
                                              └──▶ VOIDED

Draft is yours to edit. Submit moves it to PENDING_APPROVAL when your organisation requires internal sign-off; approval can come back as APPROVED or CHANGE_REQUESTED, which returns it to draft. Send delivers it and the quote becomes SENT, then VIEWED when the buyer opens it.

SIGNED is the terminal happy state, and the one that provisions.

DECLINED and EXPIRED are not dead ends: revise creates a new version of the quote carrying the same context, which is how a renegotiation works without losing the trail.

The buyer's side

A sent quote gets a public link with a token: the customer opens it, reads the terms, and signs, without an account and without logging in.

Two things follow from that link being public but unguessable:

• Rotate the token with POST /v1/quotes/{id}/rotate-token if it leaks. The old link stops working immediately.
• mark-signed exists for signatures collected elsewhere, such as a wet signature or your own e-signature provider. It records the signature and provisions exactly as an in-portal signature would.

What signing does

Signing triggers provisioning. The quote's items, prices, billing interval and anchor day become a real subscription.

Each line that states an agreed rate lands on that subscription as a negotiated price with its own window, so the first billed day is billed at the rate that was negotiated rather than at the catalog price. If the quote also agreed a term, the window closes on the day the term runs out, and the quote's agreement is recorded against the subscription at the same moment.

If provisioning fails, for example because a product was archived between sending and signing, POST /v1/quotes/{id}/orchestrate re-runs it. The quote stays signed; only the provisioning is retried.

Contract text

clauses snapshots library clauses onto the quote at creation. Snapshot is the operative word: editing the clause library afterwards does not alter a quote already sent, because what the customer signed must stay what the customer signed.

contract_terms carries free text for anything not in the library. Countersigner name and email record who signs on your side.

None of that is the commercial term. Clauses and contract terms are the words the buyer agrees to; the agreed term below is the field the billing engine reads, and it is the one that decides what the customer is charged in month fourteen.

The agreed term

The agreed term is how long the prices on this offer are the agreed ones, and it is the field an enterprise deal turns on. It is measured in weeks, months or years, counted from the day the subscription starts rather than from the day the offer was written. There is no day unit, because a deal measured in days is a trial, and a trial is a subscription phase.

It is not how long the subscription runs. A subscription that renews every month can carry a three-year agreed price, and that is the ordinary enterprise shape rather than an exotic one. The dashboard keeps the two in separate groups for exactly this reason.

Open-ended

Omit the term and the agreed rates hold until something supersedes them, which is what every negotiated rate meant before terms existed. Nothing is committed and nothing expires. A later offer for the same line closes the old rate and opens a new one.

A fixed term

State negotiated_term_unit and negotiated_term_count together and the offer agrees an end date. They travel as a pair, and one without the other is refused while the quote is still a draft.

Two things follow from a term, and they are the reason to use one. Every agreed rate on the offer expires on the same day, so six lines of one negotiation cannot drift apart. And the customer is committed for that long, which is what gives the agreement something to govern when somebody tries to cancel early.

When the term runs out

A signed quote records an agreement that continues without a term. The agreed rates lapse on their own windows, the subscription carries on at catalog prices, and agreement.term_ended is emitted so nobody has to notice by reading an invoice. The subscription itself is untouched: it is not cancelled, not renewed and not moved.

The agreement also decides what happens if somebody tries to cancel before the term is up. A quote-signed one warns and records the attempt rather than refusing it, and it governs cancellation only.

The other five endings, including renewing for another term and moving to a successor plan, live on the agreement rather than on the offer. They are covered in full on Agreements.

On a SUBSCRIPTION_UPDATE quote the agreed rates still land with the same window and still lapse on the same day. The agreement itself is recorded only where the offer provisions a new subscription.

Ramped rates

A ramp is the rate changing partway through the term, on a schedule both sides agreed in advance. It is the shape almost every multi-year deal has, and it is one field.

Take Premium Support Seat, agreed at CHF 150 per seat per month for three years and rising each year:

Code
opening rate    CHF 150.00 / seat        year 1

step 1          starts_after 1 year  ->  CHF 165.00 / seat        year 2
step 2          starts_after 2 years ->  CHF 180.00 / seat        year 3

term ends       3 years after the subscription starts

The opening rate lives on the line as negotiated_unit_amount. Each step lives in negotiated_ramp as an offset from the deal's start, never as a date, because an offer written in September for an October start that is signed in November must still step twelve months after it actually started. At provisioning the opening rate and its steps become adjacent rate windows that tile the term, so there is no instant the customer is priced by nothing and none where they are priced twice.

A ramp must satisfy three rules, all of them checked while the offer is still a draft:

1. It needs an opening rate. A step on a line still billing the catalog price would be the only agreed number on that line, with nothing to step away from. Set negotiated_unit_amount, or negotiated_tiers for a ladder.
2. It needs an agreed term. An offer can only say "165 from year two" once it has said how long the deal runs, because that is what places the step inside something.
3. The steps must ascend in time and land inside the term. No two may start at the same instant, which is checked on resolved dates rather than on the numbers you sent, so twelve months and one year are correctly treated as the same day. A step starting on or after the day the term ends is refused, because a price nobody will ever be charged is a mistake rather than a clause. At most 50 steps.

Ramps and tier ladders are different axes and neither replaces the other. A ladder is different prices at different volumes at one instant; a ramp is different prices at different times. "CHF 150 a seat, dropping above 50 seats, rising 10% a year" is both at once, and a line may carry both: send negotiated_tiers for the ladder and negotiated_ramp for the schedule. A flat agreed rate replaces the ladder for the life of the deal, which is why a metered line negotiates the rungs instead of flattening them.

Create one in the dashboard

We will offer Premium Support Seat to an existing customer at an agreed rate that holds for three years.

Create one with the API

The same offer in one call: a three-year term, an agreed opening rate, and the two steps that raise it.

Every amount is a decimal string in major units, never a number, because a JSON float does not survive a sub-cent negotiated rate. product_name and unit_amount are required by the schema and ignored on a plan-backed quote, which takes each line's name from the plan version's snapshot and its list price from the previewer; the dashboard sends empty strings for both. The agreed rate is the one that bills.

PATCH /v1/quotes/{id} restates the same fields, and clear_negotiated_term takes the offer back to open-ended. Editing the content of a quote that has already been sent pulls it back to DRAFT and rotates the buyer's link, so nobody signs the version you have just changed.

Dashboard and API names

In the dashboard	In the API
Send	POST /quotes/{id}/send
Submit for approval	POST /quotes/{id}/submit
Mark signed	POST /quotes/{id}/mark-signed
Revise	POST /quotes/{id}/revise
Void	POST /quotes/{id}/void
the buyer's link	the quote's public token
Clauses	clauses[], snapshotted at creation
How long the agreed prices hold	negotiated_term_unit (week | month | year)
For how many	negotiated_term_count, at least 1
Open-ended — no agreed end	both fields absent, or clear_negotiated_term on an update
Agreed rate	items[].negotiated_unit_amount, a decimal string in major units
Agreed tier prices	items[].negotiated_tiers
the rate steps during the term	items[].negotiated_ramp, up to 50 RampStep entries

Where quotes go next

1. A signed quote becomes a subscription, which then bills normally.
2. An offer with an agreed term also becomes an agreement, recorded against that subscription. It is what governs cancelling before the term runs out, and what emits agreement.term_ending_soon and agreement.term_ended.
3. GET /v1/quotes/{id}/events is the audit trail: sent, viewed, signed, with timestamps.
4. Attachments ride along on the quote for anything the PDF does not carry.

Reference

Topic	When you need it
Agreements	The term, its end action, and leaving early
Subscriptions	What a signed quote provisions
Prices	Where the numbers on a quote come from
Approvals	Internal sign-off before a quote can be sent
Quotes API	Every endpoint, including PDF, attachments and events