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

# Quotes & Orders

> Every order starts as a quote

## Lifecycle

```
quote: requested ──► awaiting_payment ──► approved ──► order: created
                          │                                  │
                          └──► cancelled                     ▼
                                            in_progress ──► ready_for_review ──► completed
```

1. `POST /v1/quotes` creates a quote with status **`requested`**, together with the
   documents you attach.
2. Our team reviews and prices it. The quote becomes **`awaiting_payment`** and a
   `quote.ready` webhook fires — the quote now carries priced line `items` and a
   `total`.
3. `POST /v1/quotes/{id}/approve` approves it. The quote becomes **`approved`**,
   an **order** is created (webhooks `quote.approved` and `order.created`), and the
   order is billed to your account's open invoice.
4. The order progresses through **`in_progress`** → **`ready_for_review`** →
   **`completed`**, each firing a webhook. Completed deliverables are available
   via `GET /v1/documents/{id}/download`.

## Creating quotes

The main request fields (see the
[API reference](/api-reference) for the full schema):

* `quote_type` — `academic_evaluation`, `expert_opinion_letter`, or `translation`,
  plus its type-specific fields (`evaluation_type`, `expert_letter_type`,
  `source_language`).
* **Documents** — `document_ids` (files staged via the [files API](/guides/files)),
  and/or `document_urls` (public URLs we download server-side). Up to 50 combined.
* `candidate` — the person the evaluation concerns.
* `turnaround`, `reference`, `notes`, `cc_emails`, `team`.

## Approving quotes

Approval requires **net-terms invoicing** on your account: the order is added to
your open Fortis invoice, which is closed and sent on your billing cadence. No
card payment happens in the API. Contact
[support](mailto:support@fortiseval.com) to enable invoicing.

A quote can only be approved while it is `awaiting_payment`. Failures return
`422` with an `error_code`:

| `error_code`                 | Meaning                                                           |
| ---------------------------- | ----------------------------------------------------------------- |
| `quote_not_awaiting_payment` | The quote isn't priced yet, was cancelled, or is already approved |
| `invoicing_not_enabled`      | Your account doesn't have net-terms invoicing set up              |
| `quote_superseded`           | A newer quote replaced this one on the same request               |
| `payment_declined`           | The charge could not be processed                                 |

Approval is race-safe: concurrent approve calls result in exactly one order —
subsequent calls return `quote_not_awaiting_payment`.

## Custom metadata

`PUT /v1/orders/{id}` lets you attach your own identifiers to an order:
`custom_reference` (a string shown alongside the order) and `custom_metadata`
(up to 64 key-value pairs, merged per key; set a key to `null` to remove it).