> This page is for version V1 (default). > For other versions, use one of these documentation indexes: > - V1 (default): https://docs.ottimate.com/v-1/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ottimate.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ottimate.com/_mcp/server. # Invoice lifecycle As an invoice moves through the accounts payable lifecycle, Ottimate assigns a `status` to track its progress through each stage. The `status` field is returned on every invoice object and is also accepted as a filter on [`GET /v1/invoices`](/api-reference/api-reference/invoices/get-invoices-root). ## Invoice status values Ottimate derives `status` from the invoice's underlying state — you never set it directly. | Status | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `processing` | The invoice is moving through extraction and has not yet been fully digitized. This is also the default status for any invoice that does not match one of the conditions below. | | `needs-attention` | The invoice requires manual review before it can proceed. Causes include incomplete extracted data, an unmapped vendor, a required accounting class that is not set, unmapped line items, or the invoice having been flagged. They appear under the 'Needs Attention' tab in the Ottimate UI. | | `pending-approval` | The invoice is fully coded and awaiting approval from its assigned approvers. See [Invoice approvals](/invoice-approvals). | | `ready-for-export` | The invoice has been approved and is ready for export to your ERP system. They appear under the 'Approved' tab in the Ottimate UI. | | `exported` | The invoice has been successfully exported to your ERP system. | | `inactive` | The invoice is no longer part of an active workflow. Check `sub_status` for the reason. | > **Info** > > **Statuses are evaluated in priority order**, not as independent flags. An invoice is matched against the conditions in this order: `inactive`, `processing`, `needs-attention`, `exported`, `ready-for-export`, `pending-approval` — and falls back to `processing` if none match. An invoice that is both flagged and exported, for example, resolves to `needs-attention` because that condition is evaluated first. ## Inactive sub-statuses When `status` is `inactive`, the `sub_status` field explains why. It is `null` for every other status. | Sub-status | Description | | ----------- | -------------------------------------------------------------------------------------------------------------------- | | `deleted` | The invoice was deleted. | | `merged` | The invoice was merged into another invoice. | | `archived` | The invoice was archived — either manually, or by being ingested with `status: "archived"` as a historical backfill. | | `duplicate` | The invoice was identified as a duplicate of another invoice. | > **Warn** > > **`archived` is a `sub_status`, not a `status`.** An archived invoice is returned as `status: "inactive"` with `sub_status: "archived"`. Filtering for `status=inactive` returns archived, deleted, merged, and duplicate invoices together — inspect `sub_status` to distinguish them. ## Filtering by status Pass a comma-separated list to return invoices matching any listed status: ```bash GET /v1/invoices?status=pending-approval,ready-for-export ``` When passing **more than one** status: * The date range must be within 30 days * The `search` parameter cannot be used at the same time * If you pass no date filter at all, the last 30 days are used (`date_from` defaults to 30 days ago and `date_to` to now); if you do pass dates, your values are used as given and the 30-day limit still applies > **Warn** > > **Legacy filter values.** `approved`, `incomplete`, and `archived` are accepted by the `status` query parameter but are **never returned** in an invoice's `status` field. They filter on the raw underlying invoice state, which cuts across the six statuses above, and they are only accepted as a **single** value — they cannot be combined with other statuses. > > | Legacy value | What it actually returns | > | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | `approved` | Invoices whose raw state is approved — a **mix** of `ready-for-export`, `exported`, `pending-approval`, and `needs-attention`. Not equivalent to `status=ready-for-export`. | > | `incomplete` | Invoices whose raw state is incomplete. These are all reported as `needs-attention`, but `needs-attention` is broader — it also covers unmapped vendors, missing accounting classes, unmapped items, and flagged invoices. | > | `archived` | Invoices reported as `status: "inactive"` with `sub_status: "archived"`. Narrower than `status=inactive`, which also returns `deleted`, `merged`, and `duplicate`. | > > Prefer the six documented statuses for new integrations. > **Warn** > > **An unrecognised `status` value is silently ignored.** `GET /v1/invoices?status=not-a-real-status` returns `200` with `count: 0` rather than a `400`. A typo in a status filter looks identical to "no matching invoices" — validate the value on your side before sending it. ## Updating the export status of one or more invoices In Ottimate-hosted integrations, invoices exported to an ERP are tagged with the `exported` status. If you are fetching invoices for ERP export, you can set the export status of one or more invoices with the following: | Endpoints | Operations | | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [`POST /v1/invoices/mark-exported`](/api-reference/api-reference/invoices/post-invoices-mark-exported) | Sets one or more invoices as exported. | | [`POST /v1/invoices/mark-unexported`](/api-reference/api-reference/invoices/post-invoices-mark-unexported) | Removes export status from one or more invoices | ### Update Export Status and Flag Invoices The `marked_reason` field in `POST /v1/invoices/mark-unexported` allows you to attach a note to the "Invoice History" tab. Apply notes to individual invoices or in bulk.