Resources

The invoice.v1 result, field by field.

invoice.v1 is the closed accounting object returned under data on result-bearing documents. The standalone JSON Schema is generated from the same executable contracts that validate it in production.

On this page

Document envelope

The document resource wraps the accounting result with identity, policy, and processing metadata. schema_version is always invoice.v1 on result-bearing documents; policy echoes the canonical accepted required_fields, line_items and checks.duplicate_detection settings. See Review Policy for their meaning.

Code example

{
  "id": "doc_9f3kc28d",
  "object": "document",
  "status": "completed",
  "document_type": "invoice",
  "schema_version": "invoice.v1",
  "accounting_entity_id": "client_acme",
  "policy": { "required_fields": [], "line_items": "advisory", "checks": { "duplicate_detection": true } },
  "data": { "…": "…" },
  "validation": { "…": "…" },
  "processing": { "result_expires_at": "…" }
}

accounting_entity_id is opaque caller correlation data: it namespaces duplicate matching inside your account and attributes usage, but it is not an authorization boundary and never appears inside data.

Supported required fields

policy.required_fields accepts only these JSON Pointer paths from the public contract. See how required fields affect review.

/data/customer/name
/data/customer/tax_id
/data/invoice/currency
/data/invoice/due_date
/data/invoice/issue_date
/data/invoice/number
/data/invoice/payment_terms
/data/invoice/purchase_order_number
/data/totals/amount_due
/data/totals/discount
/data/totals/other_charges
/data/totals/shipping
/data/totals/subtotal
/data/totals/tax
/data/totals/total
/data/vendor/name
/data/vendor/tax_id

Shape by status

The fields in the response depend on its status:

awaiting_upload, queued, processing: identity, policy, and processing metadata only - no data, no validation.
completed, needs_review: include data and validation; never a terminal error.
failed: includes the public error and no usable invoice result - a usable candidate with uncertain safety arrives as needs_review instead.

Money and nullability

Money is always a decimal string plus an ISO currency code - never a floating-point number, never an embedded symbol:

Code example

{ "amount": "108.25", "currency": "USD" }

Fixed-schema scalar fields are present and nullable. Missing, ambiguous, or insufficiently contextual facts remain null and never get invented - an unresolved rate or item association does not erase other readable amounts or rows. Unresolved critical fields surface in validation.checkswith actionable JSON-pointer paths.

Currency is explicit when the invoice states it; otherwise the extractor infers the most likely supported code from the overall invoice context and returns null when context is materially contradictory. An accepted inferred currency satisfies currency requirements with no inference warning. Explicit conflicting currencies require review; there is no relabeling or FX conversion.

Invoice header

Code example

{
  "number": "INV-10492",
  "issue_date": "2026-08-01",
  "due_date": "2026-08-31",
  "purchase_order_number": "PO-82941",
  "currency": "USD",
  "payment_terms": "Net 30"
}

Ambiguous dates or currency become null. When an upload contains a purchase-order page plus the invoice, purchase_order_number is populated only if the invoice segment itself states or references that value - supporting material never supplies invoice fields.

Vendor and customer objects carry identity fields such as name and tax_id with nullable address structures; addresses are plain nested objects with nullable children, not free-form text.

Totals

Code example

{
  "subtotal": { "amount": "100.00", "currency": "USD" },
  "discount": null,
  "shipping": null,
  "other_charges": null,
  "tax": { "amount": "8.25", "currency": "USD" },
  "total": { "amount": "108.25", "currency": "USD" },
  "amount_due": { "amount": "108.25", "currency": "USD" }
}

null means not present or unknown; an explicit printed zero stays an explicit zero. discount is a non-negative reduction magnitude even when the source prints a minus sign; other_charges is a signed net adjustment with explicit semantics. total is the invoice total after invoice-level adjustments and tax; amount_due is the represented payable after settlement activity such as payments or prior balances. A known value never substitutes for an unknown other, and missing monetary fields are never calculated.

Line items

Code example

{
  "description": "Industrial Widget A",
  "product_code": "WIDGET-A",
  "quantity": "2",
  "unit_of_measure": "each",
  "unit_price": { "amount": "40.00", "currency": "USD" },
  "discount": { "amount": "5.00", "currency": "USD" },
  "tax": {
    "label": "Sales Tax",
    "rate": "0.0825",
    "amount": { "amount": "6.19", "currency": "USD" }
  },
  "line_total": { "amount": "75.00", "currency": "USD" }
}

Quantities are decimal strings. unit_price is the quoted per-unit amount; line_total is the represented extended amount - one is never copied into or calculated for the other. Canceled entries that contribute no billed charge or credit are omitted; credit and reversal rows are retained with their signed amounts.

data.line_items_status reports the extraction assessment: complete, partial, or unavailable. At most 500 line items are returned; a source beyond that fails with a complexity-limit error rather than being silently truncated.

Taxes

Line-level tax is null when no line-tax structure exists; when present it keeps nullable label, decimal-fraction rate, and Money amount children. Invoice-level tax breakdowns remain available through top-level taxes[].

Tax checks verify arithmetic, not legal compliance. If the extracted data does not show whether an amount includes tax, the check returns not_evaluable instead of guessing.

How validation outcomes drive review