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, and so are the types, limits and values below.

On this page

At a glance

Every field is always present. Select an object to read its fields.

vendorobject
name tax_id address
customerobject
name tax_id address
invoiceobject
number issue_date due_date purchase_order_number currency payment_terms
line_itemsarray of objects
description product_code quantity unit_of_measure unit_price discount tax line_total
line_items_statusstring
completepartialunavailable
totalsobject
subtotal discount shipping other_charges tax total amount_due
taxesarray of objects
type label rate taxable_amount amount jurisdiction

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: The accepted review policy, with every member filled in.

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: An opaque, case-sensitive namespace of your own, such as a client ID. Duplicate detection is isolated within it and usage can be attributed to it; it is not an authorization boundary. It 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, and processing: identity and policy only - no data, validation or processing.
completed and needs_review: include data, validation and processing; 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.

Vendor and customer

vendor: The seller that issued the invoice. customer: The buyer the invoice is addressed to. Both share this shape.

namestring · nullable

The name as printed, without trademark marks or trailing commas, semicolons and colons.

tax_idstring · nullable

The tax ID. A printed scheme label such as VAT No: is removed when the identifier after it is clear.

addressobject · nullable

The postal address, or null when none is printed or none of its parts can be read.

6 child fields

line1string · nullable

First address line.

line2string · nullable

Second address line.

citystring · nullable

City or town.

regionstring · nullable

State, province or region.

postal_codestring · nullable

Postal or ZIP code.

country_codecountry code · nullable

ISO 3166-1 alpha-2 code, such as US, when unambiguous.

Invoice header

The invoice header: its number, dates, purchase order, currency and payment terms.

numberstring · nullable

The invoice number. A leading # or № is removed; leading zeros stay.

issue_datedate · nullable

The issue date. Null when the printed date is ambiguous.

due_datedate · nullable

The due date. Null when the printed date is ambiguous.

purchase_order_numberstring · nullable

The purchase order the invoice itself states or references, with a leading # or № removed. A separate purchase order page in the same upload never supplies it.

currencycurrency code · nullable

The invoice currency: as printed, or inferred from the invoice's context. Null when the context is insufficient or contradictory.

payment_termsstring · nullable

Payment terms as printed, such as Net 30.

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"
}

Line items

The invoice's billed rows. data.line_items holds at most 500 rows, kept at billed-row granularity; canceled entries that bill nothing are omitted. A source with more rows fails with a complexity-limit error rather than being shortened.

descriptionstring · nullable

The row's description, with wrapped lines merged.

product_codestring · nullable

SKU, part or product code.

quantitydecimal string · nullable

The row's quantity.

unit_of_measurestring · nullable

The unit, such as each or hours.

unit_priceMoney · nullable

The quoted amount per unit. It is never copied into or calculated from line_total.

discountMoney · nullable

The row's reduction.

Amount: never negative

taxobject · nullable

The row's tax, or null when the invoice shows no line tax. Several distinct line taxes without a printed aggregate leave it unknown; invoice-level breakdowns are in taxes.

3 child fields

labelstring · nullable

The tax label as printed.

ratedecimal string · nullable

As a decimal fraction: 8.25% is 0.0825.

Sign: never negative

amountMoney · nullable

The row's tax amount.

line_totalMoney · nullable

The row's extended amount as printed, never calculated. Credits and reversals keep their sign.

line_items_statusstring

How completely the rows were extracted. It is an AI assessment: complete is not proof that every source row was captured.

complete: The AI assessed the rows as complete. It is not proof that every source row was captured.
partial: Some rows were extracted and are kept; others are missing.
unavailable: Extraction yielded no rows and line_items is empty. It doesn't mean the invoice has none.

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" }
}

Totals

Invoice-level amounts. null means not printed or unknown; a printed zero stays zero. A known amount never fills in for an unknown one: only total is ever calculated, and only as its row describes.

subtotalMoney · nullable

The invoice charge base before invoice-level adjustments.

discountMoney · nullable

The invoice-level reduction, even when the invoice prints it with a minus sign.

Amount: never negative

shippingMoney · nullable

Shipping charges.

other_chargesMoney · nullable

The signed net of other invoice-level adjustments, when their meaning is explicit.

taxMoney · nullable

Invoice-level tax. Its breakdown is in taxes.

totalMoney · nullable

The invoice total after reductions, shipping, other charges and tax, before payments. When the invoice prints no total, it is the amount that its subtotal and adjustments, and its payable plus what was deducted from it, both give exactly; with nothing deducted, that is the payable.

amount_dueMoney · nullable

The amount currently payable. Payments, deposits, credits and prior balances can make it differ from total.

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" }
}

Taxes

The invoice-level tax breakdown, one entry per tax component. data.taxes holds at most 500 components; a source with more fails with a complexity-limit error rather than being shortened. A percentage-based fee, commission or discount is not a tax merely because it has a rate.

typestring

The tax category. It is never null: a real tax is kept even when its category can't be read.

sales_tax: Identified as sales tax.
vat: Identified as VAT.
gst: Identified as GST.
other: A clearly identified category other than sales tax, VAT or GST.
unknown: A real tax whose category can't be safely classified.

labelstring · nullable

The tax label as printed.

ratedecimal string · nullable

As a decimal fraction: 8.25% is 0.0825.

Sign: never negative

taxable_amountMoney · nullable

The amount the tax applies to.

amountMoney · nullable

The tax amount. Null when none is printed, even when tax is known not to apply; it is never turned into zero.

jurisdictionstring · nullable

The taxing jurisdiction, when printed.

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