Skip to navigation
Accounts payableInvoices

Invoice lifecycle

Learn about the life cycle of an invoice object in Ottimate

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.

Invoice status values

Ottimate derives status from the invoice’s underlying state — you never set it directly.

StatusDescription
processingThe 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-attentionThe 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-approvalThe invoice is fully coded and awaiting approval from its assigned approvers. See Invoice approvals.
ready-for-exportThe invoice has been approved and is ready for export to your ERP system. They appear under the ‘Approved’ tab in the Ottimate UI.
exportedThe invoice has been successfully exported to your ERP system.
inactiveThe invoice is no longer part of an active workflow. Check sub_status for the reason.

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-statusDescription
deletedThe invoice was deleted.
mergedThe invoice was merged into another invoice.
archivedThe invoice was archived — either manually, or by being ingested with status: "archived" as a historical backfill.
duplicateThe invoice was identified as a duplicate of another invoice.

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:

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

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 valueWhat it actually returns
approvedInvoices whose raw state is approved — a mix of ready-for-export, exported, pending-approval, and needs-attention. Not equivalent to status=ready-for-export.
incompleteInvoices 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.
archivedInvoices 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.

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:

EndpointsOperations
POST /v1/invoices/mark-exportedSets one or more invoices as exported.
POST /v1/invoices/mark-unexportedRemoves 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.