> ## Documentation Index > Fetch the complete documentation index at: https://docs.watchdog.no/llms.txt > Use this file to discover all available pages before exploring further. # Update an invoice > Merges changes against the locked current invoice. Financial changes require the complete result to pass validation; failure rolls back the entire edit. Metadata-only edits preserve existing financial errors. Equivalent numeric values are no-ops. Saving does not refresh matching or compliance analysis. ## OpenAPI ````yaml /openapi-preview.json patch /v1/invoices/{id} openapi: 3.1.0 info: title: Watchdog API (preview) version: 1.0.0 description: >- Development preview for agreements, price items, document relationships, canonical invoices, alerts and alert topics, claims and attached alerts, shared entity activity and comments, Document uploads, invoice imports, explicit invoice-agreement matching, and workflow runs. This contract is under development and is not served by api.watchdog.no. Request bodies are limited to 2 MiB (2,097,152 bytes), including all JSON fields and line data, except POST /v1/support/contact which permits 32 MiB for base64 attachments. File bytes are uploaded directly to storage. The existing public REST service retains its separate contract. servers: - url: http://localhost:3500 description: Local development Worker security: [] paths: /v1/invoices/{id}: patch: tags: - Invoices summary: Update an invoice description: >- Merges changes against the locked current invoice. Financial changes require the complete result to pass validation; failure rolls back the entire edit. Metadata-only edits preserve existing financial errors. Equivalent numeric values are no-ops. Saving does not refresh matching or compliance analysis. operationId: updateInvoice parameters: - name: X-Organization-Id in: header required: false schema: type: string description: >- Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization. - schema: type: string format: uuid required: true name: id in: path - schema: type: string minLength: 1 maxLength: 200 pattern: ^[\x21-\x7e]+$ description: >- Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request. required: false description: >- Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request. name: idempotency-key in: header requestBody: description: >- The complete encoded JSON body, including all line data, must be at most 2 MiB (2,097,152 bytes). Individual field and line-count limits also apply. required: true content: application/json: schema: type: object properties: supplier_id: type: - string - 'null' format: uuid recipient_id: type: - string - 'null' format: uuid category: type: string enum: - invoice - credit_note - self_billed_invoice invoice_number: type: string minLength: 1 maxLength: 255 title: type: - string - 'null' maxLength: 2000 issued_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ due_date: type: - string - 'null' pattern: ^\d{4}-\d{2}-\d{2}$ currency_code: type: string pattern: ^[A-Z]{3}$ total_amount_including_vat: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ total_amount_excluding_vat: type: - string - 'null' maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ original_currency_code: type: - string - 'null' pattern: ^[A-Z]{3}$ currency_conversion_rate: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ delivery: type: - object - 'null' properties: name: type: - string - 'null' maxLength: 2000 default: null date: type: - string - 'null' pattern: ^\d{4}-\d{2}-\d{2}$ default: null address: type: object properties: street: type: - string - 'null' maxLength: 2000 default: null city: type: - string - 'null' maxLength: 2000 default: null state: type: - string - 'null' maxLength: 2000 default: null postal_code: type: - string - 'null' maxLength: 2000 default: null country_code: type: - string - 'null' pattern: ^[A-Z]{2}$ default: null additionalProperties: false required: - address additionalProperties: false credit_note_invoice_reference: type: - string - 'null' maxLength: 2000 payment_reference: type: - string - 'null' maxLength: 2000 bank_account_number: type: - string - 'null' maxLength: 2000 order_references: type: array items: type: string minLength: 1 maxLength: 2000 maxItems: 50 buyer_reference: type: - string - 'null' maxLength: 2000 seller_reference: type: - string - 'null' maxLength: 2000 contract_reference: type: - string - 'null' maxLength: 2000 project_reference: type: - string - 'null' maxLength: 2000 accounting_cost: type: - string - 'null' maxLength: 2000 line_items: type: array items: type: object properties: id: type: string format: uuid line_number: type: integer exclusiveMinimum: 0 maximum: 2147483647 description: type: - string - 'null' maxLength: 2000 default: null product_code: type: - string - 'null' maxLength: 2000 default: null quantity: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ unit: type: - string - 'null' maxLength: 2000 default: null unit_price: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ discount_rate: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ default: '0' surcharge_rate: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ default: '0' vat_rate: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ default: '0' total_excluding_vat: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ period_start: type: - string - 'null' pattern: ^\d{4}-\d{2}-\d{2}$ default: null period_end: type: - string - 'null' pattern: ^\d{4}-\d{2}-\d{2}$ default: null notes: type: - string - 'null' maxLength: 2000 default: null required: - line_number - quantity - unit_price - total_excluding_vat additionalProperties: false minItems: 1 maxItems: 500 supplier_snapshot: type: - object - 'null' properties: name: type: - string - 'null' maxLength: 2000 main_name: type: - string - 'null' maxLength: 2000 department: type: - string - 'null' maxLength: 2000 organization_number: type: - string - 'null' maxLength: 2000 email: type: - string - 'null' maxLength: 2000 website: type: - string - 'null' maxLength: 2000 address: type: - object - 'null' properties: street: type: - string - 'null' maxLength: 2000 city: type: - string - 'null' maxLength: 2000 state: type: - string - 'null' maxLength: 2000 postal_code: type: - string - 'null' maxLength: 2000 country_code: type: - string - 'null' pattern: ^[A-Z]{2}$ additionalProperties: false additionalProperties: false recipient_snapshot: type: - object - 'null' properties: name: type: - string - 'null' maxLength: 2000 main_name: type: - string - 'null' maxLength: 2000 department: type: - string - 'null' maxLength: 2000 organization_number: type: - string - 'null' maxLength: 2000 email: type: - string - 'null' maxLength: 2000 website: type: - string - 'null' maxLength: 2000 address: type: - object - 'null' properties: street: type: - string - 'null' maxLength: 2000 city: type: - string - 'null' maxLength: 2000 state: type: - string - 'null' maxLength: 2000 postal_code: type: - string - 'null' maxLength: 2000 country_code: type: - string - 'null' pattern: ^[A-Z]{2}$ additionalProperties: false additionalProperties: false payment_override: type: - object - 'null' properties: outstanding_amount: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ required: - outstanding_amount additionalProperties: false extraction_confirmed: type: boolean line_item_changes: type: object properties: create: type: array items: type: object properties: line_number: type: integer exclusiveMinimum: 0 maximum: 2147483647 description: type: - string - 'null' maxLength: 2000 default: null product_code: type: - string - 'null' maxLength: 2000 default: null quantity: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ unit: type: - string - 'null' maxLength: 2000 default: null unit_price: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ discount_rate: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ default: '0' surcharge_rate: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ default: '0' vat_rate: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ default: '0' total_excluding_vat: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ period_start: type: - string - 'null' pattern: ^\d{4}-\d{2}-\d{2}$ default: null period_end: type: - string - 'null' pattern: ^\d{4}-\d{2}-\d{2}$ default: null notes: type: - string - 'null' maxLength: 2000 default: null required: - line_number - quantity - unit_price - total_excluding_vat additionalProperties: false maxItems: 500 default: [] update: type: array items: type: object properties: line_number: type: integer exclusiveMinimum: 0 maximum: 2147483647 description: type: - string - 'null' maxLength: 2000 product_code: type: - string - 'null' maxLength: 2000 quantity: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ unit: type: - string - 'null' maxLength: 2000 unit_price: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ discount_rate: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ surcharge_rate: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ vat_rate: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ total_excluding_vat: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ period_start: type: - string - 'null' pattern: ^\d{4}-\d{2}-\d{2}$ period_end: type: - string - 'null' pattern: ^\d{4}-\d{2}-\d{2}$ notes: type: - string - 'null' maxLength: 2000 id: type: string format: uuid required: - id additionalProperties: false maxItems: 500 default: [] remove: type: array items: type: string format: uuid maxItems: 500 default: [] additionalProperties: false matched_invoice_ids: type: array items: type: string format: uuid maxItems: 50 additionalProperties: false example: title: September consulting responses: '200': description: Invoice after the atomic update, or unchanged invoice for a no-op. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: '#/components/schemas/Invoice' '400': description: >- Invalid input or financially inconsistent invoice. Details identify failing fields or checks. The entire edit is rolled back. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: '#/components/schemas/Error_validation_error' example: error: code: validation_error message: >- Invalid input or financially inconsistent invoice. Details identify failing fields or checks. The entire edit is rolled back. request_id: req_example '401': description: Missing or invalid bearer credential. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. WWW-Authenticate: schema: type: string required: false description: Bearer authentication challenge, when supplied. content: application/json: schema: $ref: '#/components/schemas/Error_invalid_token' example: error: code: invalid_token message: Missing or invalid bearer credential. request_id: req_example '403': description: >- Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: >- #/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required example: error: code: forbidden message: >- Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions. request_id: req_example '404': description: The resource does not exist in the current organization. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: '#/components/schemas/Error_not_found' example: error: code: not_found message: The resource does not exist in the current organization. request_id: req_example '409': description: >- The resulting business identity matches another active invoice, or a credit note linked to a claim cannot be changed to another category. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: '#/components/schemas/Error_conflict' example: error: code: conflict message: >- The resulting business identity matches another active invoice, or a credit note linked to a claim cannot be changed to another category. request_id: req_example '429': description: The IP or authenticated credential exceeded its request limit. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. Retry-After: schema: type: string example: '60' required: true description: Seconds to wait before retrying the request. content: application/json: schema: $ref: '#/components/schemas/Error_rate_limit_exceeded' example: error: code: rate_limit_exceeded message: >- The IP or authenticated credential exceeded its request limit. request_id: req_example '500': description: >- Unexpected server failure. Include the request ID when contacting support. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: '#/components/schemas/Error_internal_error' example: error: code: internal_error message: >- Unexpected server failure. Include the request ID when contacting support. request_id: req_example '503': description: >- Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. Retry-After: schema: type: string example: '60' required: true description: Seconds to wait before retrying the request. content: application/json: schema: $ref: '#/components/schemas/Error_service_unavailable' example: error: code: service_unavailable message: >- Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided. request_id: req_example security: - ApiKeyBearer: [] - ClerkSessionBearer: [] components: schemas: Invoice: allOf: - $ref: '#/components/schemas/InvoiceSummary' - type: object properties: relationships: type: object properties: linked_credit_note_count: type: integer minimum: 0 description: >- Recorded credit notes linked to an ordinary or self-billed invoice. matched_invoice_count: type: integer minimum: 0 description: Recorded invoices matched from a credit note. line_item_count: type: integer description: >- Stored line items; retrieve through the paginated line-items endpoint. document_count: type: integer description: >- Linked source Documents; retrieve through the paginated documents endpoint. agreement_match_count: type: integer description: >- Current organization-owned, nondeleted agreement matches across the invoice. alert_count: type: integer description: >- Retained alerts in alert_summary.scope, including dismissed and outdated findings. required: - linked_credit_note_count - matched_invoice_count - line_item_count - document_count - agreement_match_count - alert_count supplier_snapshot: type: object properties: name: type: - string - 'null' organization_number: type: - string - 'null' main_name: type: - string - 'null' department: type: - string - 'null' email: type: - string - 'null' website: type: - string - 'null' address: type: object properties: street: type: - string - 'null' city: type: - string - 'null' state: type: - string - 'null' postal_code: type: - string - 'null' country_code: type: - string - 'null' required: - street - city - state - postal_code - country_code required: - name - organization_number - main_name - department - email - website - address recipient_snapshot: type: object properties: name: type: - string - 'null' organization_number: type: - string - 'null' main_name: type: - string - 'null' department: type: - string - 'null' email: type: - string - 'null' website: type: - string - 'null' address: type: object properties: street: type: - string - 'null' city: type: - string - 'null' state: type: - string - 'null' postal_code: type: - string - 'null' country_code: type: - string - 'null' required: - street - city - state - postal_code - country_code required: - name - organization_number - main_name - department - email - website - address payment_terms: type: - string - 'null' description: >- Stored printed payment terms, including conditions. Null means unavailable; never inferred from the due date. invoice_note: type: - string - 'null' description: >- Stored invoice-wide note in its original wording, separate from line notes. Null means unavailable; empty text stays empty. additional_properties: type: - array - 'null' items: type: object properties: name: type: string value: type: string source_path: type: - string - 'null' scheme: type: - string - 'null' required: - name - value description: >- Stored named business details with optional source paths. Null means unavailable; [] means inspected with none found. These do not replace financial values. original_currency_code: type: - string - 'null' currency_conversion_rate: type: - string - 'null' maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ description: >- Exact decimal string; retain as decimal text rather than a floating-point number. example: '1250.00' original_total_amount_including_vat: type: - string - 'null' maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ description: >- Exact decimal string; retain as decimal text rather than a floating-point number. example: '1250.00' payment: type: object properties: reference: type: - string - 'null' bank_account_number: type: - string - 'null' status: type: string enum: - paid - unpaid - unknown outstanding_amount: type: - string - 'null' maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ description: >- Exact decimal string; retain as decimal text rather than a floating-point number. example: '1250.00' override: type: - object - 'null' properties: outstanding_amount: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ description: >- Exact decimal string; retain as decimal text rather than a floating-point number. example: '1250.00' required: - outstanding_amount integration_outstanding_amount: type: - string - 'null' maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ description: >- Exact decimal string; retain as decimal text rather than a floating-point number. example: '1250.00' required: - reference - bank_account_number - status - outstanding_amount - override - integration_outstanding_amount delivery: type: object properties: name: type: - string - 'null' address: type: object properties: street: type: - string - 'null' city: type: - string - 'null' state: type: - string - 'null' postal_code: type: - string - 'null' country_code: type: - string - 'null' required: - street - city - state - postal_code - country_code date: type: - string - 'null' format: date required: - name - address - date references: type: object properties: order_references: type: array items: type: string buyer_reference: type: - string - 'null' seller_reference: type: - string - 'null' contract_reference: type: - string - 'null' project_reference: type: - string - 'null' accounting_cost: type: - string - 'null' credit_note_invoice_reference: type: - string - 'null' required: - order_references - buyer_reference - seller_reference - contract_reference - project_reference - accounting_cost - credit_note_invoice_reference origin: type: object properties: type: type: string enum: - structured - documents - integration - unknown import_id: type: - string - 'null' format: uuid description: >- Creating import ID, when recorded. Excludes duplicate submissions. source_system: type: - string - 'null' source_invoice_id: type: - string - 'null' required: - type - import_id - source_system - source_invoice_id required: - payment_terms - invoice_note - additional_properties - original_currency_code - currency_conversion_rate - original_total_amount_including_vat - payment - delivery - references - origin Error_validation_error: type: object properties: error: type: object properties: code: type: string enum: - validation_error message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_invalid_token: type: object properties: error: type: object properties: code: type: string enum: - invalid_token message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required: type: object properties: error: type: object properties: code: type: string enum: - forbidden - token_disabled - organization_required - insufficient_role - mfa_required message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_not_found: type: object properties: error: type: object properties: code: type: string enum: - not_found message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_conflict: type: object properties: error: type: object properties: code: type: string enum: - conflict message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_rate_limit_exceeded: type: object properties: error: type: object properties: code: type: string enum: - rate_limit_exceeded message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_internal_error: type: object properties: error: type: object properties: code: type: string enum: - internal_error message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_service_unavailable: type: object properties: error: type: object properties: code: type: string enum: - service_unavailable message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error InvoiceSummary: type: object properties: id: type: string format: uuid extraction_confirmed: type: boolean readOnly: true description: >- Explicit human review acknowledgment; independent of extraction confidence and financial validity. extraction_confirmed_at: type: - string - 'null' format: date-time readOnly: true extraction_confirmed_by_user_id: type: - string - 'null' readOnly: true invoice_number: type: - string - 'null' title: type: - string - 'null' category: type: string enum: - invoice - credit_note - self_billed_invoice issued_date: type: - string - 'null' format: date due_date: type: - string - 'null' format: date created_at: type: string format: date-time updated_at: type: string format: date-time deleted_at: type: - string - 'null' format: date-time currency_code: type: - string - 'null' total_amount_excluding_vat: type: - string - 'null' maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ description: >- Exact decimal string; retain as decimal text rather than a floating-point number. example: '1250.00' total_amount_including_vat: type: - string - 'null' maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ description: >- Exact decimal string; retain as decimal text rather than a floating-point number. example: '1250.00' financially_valid: type: boolean readOnly: true description: >- Deterministic arithmetic within a tolerance of 1 currency unit. Does not imply extraction accuracy, compliance, or human approval. financial_errors: type: array items: type: object properties: code: type: string enum: - missing_financial_inputs - line_calculation_mismatch - invoice_total_mismatch - invoice_subtotal_mismatch - category_amount_mismatch field: type: string message: type: string required: - code - field - message readOnly: true alert_summary: $ref: '#/components/schemas/InvoiceAlertSummary' supplier_name: type: - string - 'null' description: Current canonical supplier name. Used by supplier ordering. recipient_name: type: - string - 'null' description: Current canonical recipient name. Used by recipient ordering. review_recommended: type: boolean readOnly: true description: >- Review is recommended for low or medium unconfirmed extraction confidence, an unmatched credit note, or financial invalidity. Uses the same predicate as the review_recommended filter. extraction_confidence: type: string enum: - high - mid - low - unknown description: >- Lowest original header/line confidence from the creating import, when both stages have reliable evidence. Structured, XML and unavailable historical evidence are unknown; manual confirmation does not change this value. relationships: type: object properties: linked_credit_note_count: type: integer minimum: 0 description: >- Recorded credit notes linked to an ordinary or self-billed invoice. matched_invoice_count: type: integer minimum: 0 description: Recorded invoices matched from a credit note. required: - linked_credit_note_count - matched_invoice_count description: >- Recorded org-owned links including soft-deleted counterparts. A match does not establish financial resolution. supplier_id: type: - string - 'null' format: uuid description: Current canonical supplier ID. recipient_id: type: - string - 'null' format: uuid description: Current canonical recipient ID. supplier_snapshot: type: object properties: name: type: - string - 'null' organization_number: type: - string - 'null' required: - name - organization_number description: Supplier details captured on the invoice. recipient_snapshot: type: object properties: name: type: - string - 'null' organization_number: type: - string - 'null' required: - name - organization_number description: Recipient details captured on the invoice. required: - id - extraction_confirmed - extraction_confirmed_at - extraction_confirmed_by_user_id - invoice_number - title - category - issued_date - due_date - created_at - updated_at - deleted_at - currency_code - total_amount_excluding_vat - total_amount_including_vat - financially_valid - financial_errors - alert_summary - supplier_name - recipient_name - review_recommended - extraction_confidence - relationships - supplier_id - recipient_id - supplier_snapshot - recipient_snapshot InvoiceAlertSummary: type: object properties: scope: type: object properties: type: type: string enum: - invoice - selected_agreements description: >- invoice evaluates overall coverage and all retained alerts; selected_agreements evaluates only selected current matches. agreement_ids: type: - array - 'null' items: type: string format: uuid maxItems: 50 description: >- Null means overall invoice coverage; otherwise only these selected, currently matched agreements. required: - type - agreement_ids checks: type: object properties: status: type: string enum: - not_checkable - checking - not_checked - completed - incomplete completed: type: integer minimum: 0 description: >- Currently matched agreements with a completed check, including outdated or unknown check inputs reported in reasons. total: type: integer minimum: 0 description: Currently matched, nondeleted agreements. reasons: type: array items: type: string enum: - credit_note - credit_note_matched - no_agreements - missing - failed - cancelled - outdated - invoice_changed - unknown description: >- outdated means a completed check read an earlier agreement version or invoice; invoice_changed accompanies it when the invoice is what moved. credit_note_matched means the invoice has a linked completed, nondeleted credit note; active partial or shared credits also block checks. required: - status - completed - total - reasons counts: type: object properties: pending: type: integer minimum: 0 claimed: type: integer minimum: 0 dismissed: type: integer minimum: 0 credited: type: integer minimum: 0 required: - pending - claimed - dismissed - credited description: All retained alerts, including dismissed and outdated alerts. is_fully_credited: type: boolean description: >- A completed, nondeleted credit note uniquely targets this invoice and offsets its total including VAT within 1 currency unit, in the same currency. has_credit_note_match: type: boolean description: >- A recorded match, not verification that findings were financially resolved. required: - scope - checks - counts - is_fully_credited - has_credit_note_match securitySchemes: ApiKeyBearer: type: http scheme: bearer description: >- Personal API key. Send X-Organization-Id. The required cumulative level is listed in x-watchdog-permission. ClerkSessionBearer: type: http scheme: bearer description: Clerk session with an active organization. ````