> ## Documentation Index
> Fetch the complete documentation index at: https://crevio.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quotes & deals

> Track sales opportunities through a pipeline, send quotes customers sign online, and turn an accepted quote into an invoice.

**Service businesses win work before they bill it. Deals track each opportunity from first contact to won or lost, and quotes are the priced offer a customer signs online.** When the customer accepts a quote, Crevio creates the invoice for it and marks its deal won.

You can ask Crevio to "quote Jane for the kitchen remodel" and the agent drafts the quote with the same endpoints below. It asks you before it sends one.

## The flow

1. Create a deal for the contact (`POST /deals`). Optional: a quote works without one.
2. Create a draft quote with its line items (`POST /quotes`).
3. Send it (`POST /quotes/{id}/send`). Crevio emails the customer a link to the quote's `public_url`, with the quote attached as a PDF.
4. The customer reads the quote there, types their name to sign it, and accepts or declines.
5. On acceptance, Crevio creates an invoice for the quote's total and emails it to the customer. The quote's `invoice` is that invoice, and its deal moves to `won`.

While the customer decides, Crevio tells you when they open the quote and reminds them if they don't answer.

## 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:

| Stage | Meaning |
| - | - |
| `lead`, `qualified`, `proposal` | The open stages a new business starts with. Rename them, reorder them, or add your own. |
| `won` | Closed won. Accepting a quote moves its deal here and sets `won_at`. |
| `lost` | Closed lost. Moving here sets `lost_at` and keeps the `reason` you give as `lost_reason`. |

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.

```bash theme={null}
curl -X POST https://api.crevio.co/v1/deals \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": "con_xyz789",
    "title": "Kitchen remodel",
    "value": 1200000,
    "expected_close_on": "2026-12-15"
  }'
```

`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`.

```bash theme={null}
curl -X POST https://api.crevio.co/v1/deal_stages \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Site visit", "position": 2 }'
```

The key is derived from the name (`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

Set `next_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:

```bash theme={null}
curl "https://api.crevio.co/v1/deals?next_step_due=overdue,today" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

`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](https://crevio.co/docs/developer/guides/activities.md).

### Moving a deal

`PATCH /deals/{id}` changes the deal's details but never its stage. Move it with its own endpoint:

```bash theme={null}
curl -X POST https://api.crevio.co/v1/deals/deal_abc123/move \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "stage": "lost", "reason": "Went with a cheaper bid" }'
```

`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`.

```bash theme={null}
curl "https://api.crevio.co/v1/deals?stage=lead,qualified" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## Quotes

A quote (`quote_...`) has a number (`Q-000001`, counting up per business), line items, and a status:

| Status | Meaning |
| - | - |
| `draft` | Being written. Only a draft can be edited or deleted. |
| `sent` | Emailed to the customer and waiting for an answer. |
| `accepted` | Signed by the customer. Final. |
| `declined` | Turned down by the customer. Final. |
| `expired` | Passed `expires_on` without an answer. Final. |
| `canceled` | Withdrawn by you. Final. |

### Create a quote

```bash theme={null}
curl -X POST https://api.crevio.co/v1/quotes \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deal": "deal_abc123",
    "title": "Kitchen remodel",
    "message": "Thanks for having us out on Tuesday. Here is what we discussed.",
    "terms": "50% due on acceptance, the rest on completion.",
    "expires_on": "2026-12-31",
    "lines": [
      { "description": "Cabinets and installation", "quantity": 1, "unit_amount": 850000 },
      { "description": "Countertops", "quantity": 2, "unit_amount": 175000 }
    ]
  }'
```

With `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 with `discount_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

```bash theme={null}
curl -X POST https://api.crevio.co/v1/quotes/quote_abc123/send \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

Sending emails the customer. When Crevio's agent sends a quote, it asks the business owner first, unless they have set quote sending to always allow. A send can refuse with code:

| Code | Why |
| - | - |
| `not_draft` | The quote was already sent, or is closed. |
| `no_lines` | The quote has no line items. |
| `total_too_low` | The total is below the smallest amount the currency can be charged. |
| `no_contact_email` | The contact has no email address to send to. |

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`)

Turn both off with `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

| Event | When |
| - | - |
| `deal.created` | A deal is added. |
| `deal.stage_changed` | A deal moves to another stage. The new stage is the object's `stage`. The previous stage is not included; the `stage` activity it writes has both in `metadata`. |
| `quote.sent` | A quote is emailed to the customer. |
| `quote.viewed` | The customer opens a sent quote, the first time and again when they come back. `view_count` counts their visits. |
| `quote.accepted` | The customer signs and accepts. `invoice` arrives expanded. |
| `quote.declined` | The customer declines. Their reason is in `decline_reason`. |
| `quote.expired` | A sent quote passes its expiry date unanswered. |
| `quote.canceled` | You cancel a quote. |

After `quote.accepted`, follow the invoice with `invoice.paid`. See [Webhooks](https://crevio.co/docs/developer/guides/webhooks.md).

## Next steps

* [Subscriptions & billing](https://crevio.co/docs/developer/guides/subscriptions-and-billing.md): the invoice an accepted quote becomes
* [Webhooks](https://crevio.co/docs/developer/guides/webhooks.md): signatures, retries and every event


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.