# Extract invoice line items to JSON with an API

> Extract invoice header fields and every line item (code, description, quantity, unit price, amount) to JSON with the Reducto Extract API.

Canonical: https://reducto.ai/cookbooks/invoice-line-items-to-json

Send the invoice to Reducto Extract with a JSON schema that has header fields and a line_items array. You get back vendor, invoice number, dates, totals and one object per line item with code, description, quantity, unit price and amount. The schema is plain JSON Schema, so you can add fields such as tax lines or GL codes.

## What you'll build

Synthetic freight invoice (or your own file)

- Write a JSON schema with the header fields you need and a line_items array.
- Upload the invoice or pass a public URL.
- Call /extract with the schema.
- Check that the sum of line item amounts equals the subtotal before posting.

## Setup

Grab an API key from <a href="https://studio.reducto.ai" rel="noopener noreferrer" target="_blank">studio.reducto.ai</a> -> API Keys -> Create new API key, then set it and install the SDK:

```bash
export REDUCTO_API_KEY="your-api-key-here"
pip install reductoai   # or: npm install reductoai
```

## Step 1: Call `/extract`

The options that matter for this job:

- `instructions.schema`: Arrays in the schema return every row.
- `parsing.settings.model`: Reads dense and scanned invoice tables.
- `settings.citations.enabled`: Turn on to get the page and position of each value.

```python
# pip install reductoai
from pathlib import Path
from reducto import Reducto

client = Reducto()  # reads REDUCTO_API_KEY

upload = client.upload(file=Path("invoice.pdf"))
result = client.extract.run(
    input=upload.file_id,
    instructions={
        "schema": {
            "type": "object",
            "properties": {
                "vendor_name": {
                    "type": "string",
                    "description": "Company that issued the invoice.",
                },
                "invoice_number": {
                    "type": "string",
                    "description": "Invoice number as printed.",
                },
                "invoice_date": {
                    "type": "string",
                    "description": "Invoice date, YYYY-MM-DD.",
                },
                "due_date": {
                    "type": "string",
                    "description": "Payment due date, YYYY-MM-DD.",
                },
                "purchase_order": {
                    "type": "string",
                    "description": "Customer purchase order number, if printed.",
                },
                "currency": {
                    "type": "string",
                    "description": "ISO 4217 currency code.",
                },
                "line_items": {
                    "type": "array",
                    "description": "Every billed line, in order. Join descriptions that wrap onto a second line.",
                    "items": {
                        "type": "object",
                        "properties": {
                            "item_code": {
                                "type": "string",
                                "description": "Item or service code.",
                            },
                            "description": {
                                "type": "string",
                                "description": "Full line description.",
                            },
                            "quantity": {
                                "type": "number",
                                "description": "Billed quantity.",
                            },
                            "unit_price": {
                                "type": "number",
                                "description": "Price per unit.",
                            },
                            "amount": {
                                "type": "number",
                                "description": "Line total.",
                            },
                        },
                        "required": [
                            "description",
                            "amount",
                        ],
                    },
                },
                "subtotal": {
                    "type": "number",
                    "description": "Sum of line items before tax.",
                },
                "tax": {
                    "type": "number",
                    "description": "Total tax. 0 if exempt.",
                },
                "total": {
                    "type": "number",
                    "description": "Total amount due.",
                },
            },
            "required": [
                "invoice_number",
                "line_items",
                "total",
            ],
        },
    },
    parsing={
        "settings": {
            "model": "r-1",
        },
    },
    settings={
        "citations": {
            "enabled": False,
        },
    },
)
print(result)
```

```javascript
// npm install reductoai

const client = new Reducto(); // reads REDUCTO_API_KEY

const upload = await client.upload({ file: fs.createReadStream("invoice.pdf") });
const result = await client.extract.run({
  input: upload.file_id,
  instructions: {
    schema: {
      type: "object",
      properties: {
        vendor_name: {
          type: "string",
          description: "Company that issued the invoice.",
        },
        invoice_number: {
          type: "string",
          description: "Invoice number as printed.",
        },
        invoice_date: {
          type: "string",
          description: "Invoice date, YYYY-MM-DD.",
        },
        due_date: {
          type: "string",
          description: "Payment due date, YYYY-MM-DD.",
        },
        purchase_order: {
          type: "string",
          description: "Customer purchase order number, if printed.",
        },
        currency: {
          type: "string",
          description: "ISO 4217 currency code.",
        },
        line_items: {
          type: "array",
          description: "Every billed line, in order. Join descriptions that wrap onto a second line.",
          items: {
            type: "object",
            properties: {
              item_code: {
                type: "string",
                description: "Item or service code.",
              },
              description: {
                type: "string",
                description: "Full line description.",
              },
              quantity: {
                type: "number",
                description: "Billed quantity.",
              },
              unit_price: {
                type: "number",
                description: "Price per unit.",
              },
              amount: {
                type: "number",
                description: "Line total.",
              },
            },
            required: [
              "description",
              "amount",
            ],
          },
        },
        subtotal: {
          type: "number",
          description: "Sum of line items before tax.",
        },
        tax: {
          type: "number",
          description: "Total tax. 0 if exempt.",
        },
        total: {
          type: "number",
          description: "Total amount due.",
        },
      },
      required: [
        "invoice_number",
        "line_items",
        "total",
      ],
    },
  },
  parsing: {
    settings: {
      model: "r-1",
    },
  },
  settings: {
    citations: {
      enabled: false,
    },
  },
});
console.log(JSON.stringify(result, null, 2));
```

Or with curl:

```bash
# 1. Upload the file (or pass a public URL as "input" and skip this step)
curl -s https://platform.reducto.ai/upload \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -F file=@invoice.pdf
# => {"file_id": "reducto://..."}

# 2. Run extract
curl -s https://platform.reducto.ai/extract \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "reducto://FILE_ID",
  "instructions": {
    "schema": {
      "type": "object",
      "properties": {
        "vendor_name": {"type": "string", "description": "Company that issued the invoice."},
        "invoice_number": {"type": "string", "description": "Invoice number as printed."},
        "invoice_date": {"type": "string", "description": "Invoice date, YYYY-MM-DD."},
        "due_date": {"type": "string", "description": "Payment due date, YYYY-MM-DD."},
        "purchase_order": {"type": "string", "description": "Customer purchase order number, if printed."},
        "currency": {"type": "string", "description": "ISO 4217 currency code."},
        "line_items": {
          "type": "array",
          "description": "Every billed line, in order. Join descriptions that wrap onto a second line.",
          "items": {
            "type": "object",
            "properties": {
              "item_code": {"type": "string", "description": "Item or service code."},
              "description": {"type": "string", "description": "Full line description."},
              "quantity": {"type": "number", "description": "Billed quantity."},
              "unit_price": {"type": "number", "description": "Price per unit."},
              "amount": {"type": "number", "description": "Line total."}
            },
            "required": ["description", "amount"]
          }
        },
        "subtotal": {"type": "number", "description": "Sum of line items before tax."},
        "tax": {"type": "number", "description": "Total tax. 0 if exempt."},
        "total": {"type": "number", "description": "Total amount due."}
      },
      "required": ["invoice_number", "line_items", "total"]
    }
  },
  "parsing": {"settings": {"model": "r-1"}},
  "settings": {"citations": {"enabled": false}}
}'
```

## Step 2: Read the result

On the sample (a synthetic freight invoice), the job-specific part of the response:

```json
{
  "vendor_name": "Silverpine Freight Lines",
  "invoice_number": "SFL-2026-04417",
  "invoice_date": "2026-10-21",
  "due_date": "2026-11-20",
  "line_items": [
    {
      "item_code": "FRT-1001",
      "description": "Linehaul, Reno NV to Boise ID, 53ft dry van BOL 88213-A, 2 stops",
      "quantity": 1,
      "unit_price": 2450,
      "amount": 2450
    },
    {
      "item_code": "FSC-01",
      "description": "Fuel surcharge (22.5% of linehaul)",
      "quantity": 1,
      "unit_price": 551.25,
      "amount": 551.25
    }
  ],
  "...": "4 more line items"
}
```

Every line item comes back as its own object, so totals can be checked against the invoice before posting.

[Full response format ->](https://docs.reducto.ai/extract/response-format)

## When to use something else

- **Extract with a line_items array**: for invoices, receipts and purchase orders.
- **Parse**: when you want the whole document as Markdown rather than fields.
- **Split first**: when invoices arrive inside mixed packets.

## Where this goes next

- [Extract docs](https://docs.reducto.ai/extract)
- [Best invoice OCR software](/guides/best-invoice-ocr-software)
- [Best accounts payable OCR software](/guides/best-accounts-payable-ocr-software)
- [Reducto Extract](/extract)

Try one receipt free, no signup, with the [receipt to Excel tool](/tools/receipt-to-excel).
