The flow
- Create a deal for the contact (
POST /deals). Optional: a quote works without one. - Create a draft quote with its line items (
POST /quotes). - Send it (
POST /quotes/{id}/send). Crevio emails the customer a link to the quote’spublic_url, with the quote attached as a PDF. - The customer reads the quote there, types their name to sign it, and accepts or declines.
- On acceptance, Crevio creates an invoice for the quote’s total and emails it to the customer. The quote’s
invoiceis that invoice, and its deal moves towon.
Deals
A deal (deal_...) belongs to one contact and sits in one stage. Each business has its own open stages, plus two closed ones every pipeline shares:
A deal starts in the first open stage unless you pass
stage. Its description says what the deal is about, and next_step with next_step_due_on says what to do next and by when.
value is in the currency’s smallest unit, like every amount in the API. The currency defaults to the business’s display currency.
Stages
GET /deal_stages lists every stage a deal can be in: the open ones in board order, then won and lost. A stage’s id is its key, the value a deal carries in stage.
site_visit) unless you pass key, and it never changes. A business has at most 12 open stages. PATCH /deal_stages/{key} renames a stage or moves it to another position. won and lost can’t be changed.
One open stage has quote_sent: true: sending a quote moves its deal there when the deal is in an earlier stage. New businesses have it on proposal. Set quote_sent: true on another stage to move the flag.
DELETE /deal_stages/{key}?move_deals_to=qualified removes a stage and moves its deals. move_deals_to is required while the stage has deals. Removing the last open stage, or naming the stage itself as the destination, answers 400 with code invalid_removal.
Next steps and notes
Setnext_step and next_step_due_on on create or update. On the due date, the team gets a reminder in the morning, in the business’s time zone, while the deal is open. Find what needs doing:
next_step_due takes overdue, today, or both. It only returns open deals.
A deal’s history lives on its contact’s timeline. Log a call summary or a note with POST /activities and deal, and read it back with GET /activities?deal=deal_abc123. Every stage move is recorded there too, as a stage activity. See Activities.
Moving a deal
PATCH /deals/{id} changes the deal’s details but never its stage. Move it with its own endpoint:
stage is any key from GET /deal_stages. position places the deal within its stage, starting at 1. Leave it out to put the deal last. A closed deal can be reopened by moving it back to an open stage, which clears won_at, lost_at and lost_reason. Moving a deal to a stage that doesn’t exist, or straight from won to lost, answers 400 with code invalid_transition.
Filter by stage with a comma-separated list of keys. An unknown key answers 400.
Quotes
A quote (quote_...) has a number (Q-000001, counting up per business), line items, and a status:
Create a quote
deal, the contact and currency default to the deal’s. Without it, contact is required. subtotal is the sum of each line’s quantity times unit_amount, and total is the subtotal less any discount.
A line can name the catalog price it sells with price (price_...). You still send its description and unit_amount. The price must be a fixed, one-time price in the quote’s currency: a recurring, pay-what-you-want or other-currency price answers 422, and one that doesn’t exist answers 404.
Discounts
Take a discount off the subtotal withdiscount_percent_off (like 10 or 12.5) or discount_amount_off (in the smallest unit), never both. Sending both answers 422. discount_label names it on the quote, and defaults to “Discount”. The quote returns the result as discount_amount. Send null to remove a discount from a draft. The discounted total must still be at least the smallest amount the currency can be charged, or the quote answers 422.
Tax
tax_note says how tax applies to the quote: prices_include_tax, tax_added_at_checkout, or null when the business doesn’t collect tax. It follows the checkout configuration until the quote is sent, then stays fixed.
For a retainer or any other recurring work, set billing to recurring and interval to month or year. Accepting it creates an invoice for a subscription price, so paying the invoice starts the subscription.
PATCH /quotes/{id} edits a draft. Sending lines replaces every line. Once a quote is sent its content is frozen, and an edit answers 422 with code quote_not_editable. To change a sent quote, cancel it and create a new one.
Send a quote
The email carries the quote as a PDF, and the customer can download the same PDF from the quote page.
What the customer sees
public_url is set once the quote is sent and is null on a draft. The page shows the quote and lets the customer accept by typing their name, or decline with an optional reason. Acceptance records signer_name, accepted_at and document_digest, a SHA-256 hash of the quote’s content at the moment of signing. The signer’s IP address and browser are stored as evidence but not returned by the API.
A quote past its expires_on can no longer be accepted. Crevio marks unanswered sent quotes expired once a day.
Views and reminders
When the customer opens the quote, Crevio records it:first_viewed_at, last_viewed_at, and view_count, which counts visits more than an hour apart. Your own team’s views are not counted. You get a notification on the first view, and again when they come back, at most once a day. Each of those also sends quote.viewed.
If the customer hasn’t answered, Crevio emails them a reminder:
- once if they haven’t opened the quote 3 days after it was sent (
unviewed_nudge_sent_at) - once 3 days before it expires (
reminder_sent_at)
quote_reminder_emails: false on PATCH /checkout_configuration.
Cancel or delete
POST /quotes/{id}/cancel withdraws a draft or sent quote, so its link stops accepting signatures. An accepted, declined or expired quote cannot be canceled (not_cancelable): void its invoice instead if you need to stop the payment.
DELETE /quotes/{id} removes a draft. A quote that was sent stays on record, and deleting it answers 400 with code not_draft.
Webhooks
After
quote.accepted, follow the invoice with invoice.paid. See Webhooks.
Next steps
- Subscriptions & billing: the invoice an accepted quote becomes
- Webhooks: signatures, retries and every event

