Skip to main content
Refresh an invoice’s agreement relationships, or discover invoices for one agreement. Matching uses supplier and recipient coverage, dates and invoice-line periods, agreement status, filters, and optional smart criteria. Financial validity and human approval do not exclude invoices.
For an agreement, use POST /v1/agreements/{id}/match-invoices with the same headers. No request body is required. New work returns 202 and workflow_run_id after execution acceptance, with Location pointing to its run. Idempotent replays return 200 with the original identity. If acceptance is unconfirmed, inspect the run in the error’s Location. Replaying an idempotency key does not dispatch again; use a fresh key for a new attempt. Each fresh command supersedes active matching for the same target. Published relationships remain; the new run rechecks hard filters and reuses unchanged positive smart decisions. Follow workflow runs and items for progress and cancellation. Each item identifies one invoice. An invoice refresh has one item; an agreement refresh discovers invoice items and leaves progress.total unknown until discovery closes. Zero matching candidates can complete successfully. Each successful invoice publishes independently; failed invoices retain their previous relationships. Item results contain matched, created, and removed counts, up to 100 relationship IDs, and a link to the full paginated collection.
Use GET /v1/agreements/{id}/invoices for the reverse direction. Both collections include stable relationship IDs, invoice and agreement IDs, timestamps, and bounded resource summaries. Follow next_cursor until it is null. Pages default to 50 and allow at most 100, ordered by relationship creation time and UUID ascending. Cursors are bound to the organization and target. Archived agreement relationships remain readable. Deleted resources follow the usual resource visibility rules. Inactive agreements preserve existing relationships. Reads use persisted matches and agree with invoice agreement filters and match counts. Unchanged positive smart decisions can be reused. Changed configuration or invoice evidence requires evaluation. New commands with changed target inputs replace active API work for that same target. Cancellation preserves completed items and other targets’ runs. After failure, partial failure, or cancellation, a fresh command uses current inputs and links unsuccessful predecessors; technical retries keep their identities. Reads require Read. Matching and cancellation require Write, using the same organization, role, and ownership checks as other endpoints. Matching does not approve invoices or start compliance checks. When it removes a match, the pair’s alerts are deleted, unless a claim that is not cancelled holds one of them that is not dismissed, and its unfinished checks are cancelled; completed compliance checks are kept. Saving a resource does not start matching automatically.