> ## Documentation Index
> Fetch the complete documentation index at: https://lmn.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoices

> Read the commercial invoice for a secured order, list invoices per dealer, and download the PDF.

Every order that reaches `secured` gets one commercial invoice, owned and issued by LMN. It is the amount the partner owes LMN for that order — the settlement document that was previously shared out-of-band as a payment-due report. Four read-only routes expose it; nothing about an invoice is mutable through the partner API.

| Route                                    | Returns                                                                      |
| ---------------------------------------- | ---------------------------------------------------------------------------- |
| `GET /v1/invoices`                       | Paginated list, filterable by dealer / status / shipment month / issue date. |
| `GET /v1/invoices/{invoice_id}`          | One [Invoice](/schemas#invoice).                                             |
| `GET /v1/invoices/{invoice_id}/document` | The PDF (`application/pdf`), any published version.                          |
| `GET /v1/orders/{id}/invoice`            | The order's newest invoice.                                                  |

Every order response also carries an [`invoice` summary](/schemas#orderinvoicesummary) (`null` when none), and issuing fires the [`invoice.issued`](/webhooks/event-types#invoice-issued) webhook.

## Lifecycle

```
draft → issued → paid
  └───────┴────────┴──→ void
```

* **`draft`** — created automatically the moment the order transitions to `secured`. **Drafts are visible on every route above** (and as `Order.invoice` with `status: draft`), with `number: null` and `document_url: null`. Draft amounts track the order and may change between reads — treat them as indicative until issued.
* **`issued`** — LMN ops reviewed the draft, entered the consignee and shipment month, and published it: the number is assigned, `version` becomes `1`, the PDF is available, and `invoice.issued` fires. Amounts are frozen.
* **Re-issue** — LMN may correct an issued (or paid) invoice, e.g. to complete the packing list once the container is loaded. The **number never changes**; `version` increments, a new PDF is published, and `invoice.issued` fires again with `data.previous_version`. Earlier versions' PDFs remain downloadable.
* **`paid`** — LMN ops recorded the payment (`paid_at`). No webhook — read it from `Order.invoice` or these routes.
* **`void`** — terminal. The record stays readable with `void_reason`; a new draft may then be created for the same order and receives the next number on issue. No webhook.

<Note>
  **One live invoice per order.** `GET /v1/orders/{id}/invoice` and `Order.invoice` always return the order's *newest* invoice, so after a void you see the voided record until LMN creates a fresh draft.
</Note>

## Invoice numbers

`{prefix}_{YYYY}_{MM}_{seq}` — a per-partner prefix, the four-digit year and two-digit month of `shipment_month`, and a sequence per `(partner, environment, shipment month)` starting at `001`: `SKL_2026_09_001`, `SKL_2026_09_002`, … The sequence may exceed three digits (`_1000`) and is never zero-padded beyond three. Sandbox and production sequences are independent, so the same number can exist in both environments. Gaps are possible (a numbered draft that was voided) and carry no meaning.

## Pricing is bundled

`amounts.price` is one figure. LMN's commission and the partner discount from [`pricing.discount_config`](/schemas#pricing) are realised inside it — against the actual hammer price, which may be lower than `max_bid_amount_usd` — but are **not itemised** on the API or the PDF, exactly as on the paper invoice. `ocean_freight` appears as its own line only when LMN lists it separately (otherwise it is inside `price`); `insurance` is an optional additional line. `total = price + ocean_freight + insurance`.

Amounts are numbers in **major units with at most 2 decimals**, unlike the whole-USD integers on `Order.amounts`. Partners recomputing from `Order.amounts` may see a ≤\$1 difference from FX rounding — the invoice is authoritative.

## Document URLs are pinned

Every `document_url` — on the invoice, on `Order.invoice`, and inside the webhook — ends in `?version=N` for the version that payload describes. A URL you stored from version 1 keeps returning the version-1 PDF after a re-issue. Call the route without `version` for the current PDF.

***

## GET /v1/invoices — List

```bash theme={null}
curl -H "x-api-key: $KEY" \
  "https://api.lmnauto.com/v1/invoices?dealer_id=shekel-dealer-123&status=issued,paid&limit=50"
```

Newest `created_at` first. Same envelope and cursor rules as [`GET /v1/orders`](/endpoints/orders#get-/v1/orders-—-list). Drafts are included unless you exclude them with `status`. Filters combine with AND semantics.

| Param                      | Description                                                                        |
| -------------------------- | ---------------------------------------------------------------------------------- |
| `dealer_id`                | Only invoices whose `dealer_id` equals this value.                                 |
| `status`                   | A single status or a CSV — `draft`, `issued`, `paid`, `void` (e.g. `issued,paid`). |
| `shipment_month`           | `YYYY-MM`. Only invoices sequenced under this shipment month.                      |
| `issued_from`, `issued_to` | ISO 8601 with offset. Bounds on `issued_at`.                                       |
| `cursor`, `limit`          | Opaque cursor from `next_cursor`; `limit` default 50, max 200.                     |

### Response — `200 OK`

```json theme={null}
{
  "data": [
    {
      "id": "01J8...",
      "number": "SKL_2026_09_001",
      "version": 1,
      "status": "issued",
      "order_id": "01HXYZ...",
      "dealer_id": "shekel-dealer-123",
      "currency": "USD",
      "amounts": { "price": 20197, "ocean_freight": null, "insurance": null, "total": 20197 },
      "shipment_month": "2026-09",
      "document_url": "https://api.lmnauto.com/v1/invoices/01J8.../document?version=1",
      "issued_at": "2026-09-02T19:49:00+09:00",
      "created_at": "2026-09-01T10:00:00+09:00",
      "updated_at": "2026-09-02T19:49:00+09:00"
    }
  ],
  "next_cursor": null
}
```

Each entry is the full [Invoice](/schemas#invoice) resource (abbreviated above).

### Errors

| Code               | HTTP | Condition                                                                                  |
| ------------------ | ---- | ------------------------------------------------------------------------------------------ |
| `validation_error` | 400  | Malformed filter value (unknown `status`, bad `shipment_month` or date), or `limit` > 200. |
| `invalid_cursor`   | 400  | Cursor not issued by this endpoint. Restart pagination.                                    |

***

## GET /v1/invoices/\{invoice\_id} — Detail

```bash theme={null}
curl -H "x-api-key: $KEY" https://api.lmnauto.com/v1/invoices/01J8...
```

### Response — `200 OK`

```json theme={null}
{
  "id": "01J8...",
  "number": "SKL_2026_09_001",
  "version": 1,
  "status": "issued",
  "order_id": "01HXYZ...",
  "dealer_id": "shekel-dealer-123",
  "vehicle": {
    "vehicle_id": "glovis_20260820_1064_2345",
    "vin": "WDC0J6EB2JF335313",
    "license_plate": "12가3456",
    "make": "Mercedes-Benz",
    "model": "GLC43",
    "year": 2018,
    "fuel_type": "gasoline",
    "cc": null,
    "weight_kg": null
  },
  "consignee": {
    "name": "ADAMU MOTORS",
    "address": "12 Adeola Odeku Street, Victoria Island, Lagos, Nigeria",
    "email": "accounts@adamumotors.example",
    "phone": "+234 800 000 0000",
    "company_registration": "RC1234567"
  },
  "currency": "USD",
  "amounts": { "price": 20197, "ocean_freight": null, "insurance": null, "total": 20197 },
  "terms": { "payment": "100% in advance by T/T", "incoterm": "CFR", "port": "Incheon", "country_of_origin": "Korea" },
  "shipment_month": "2026-09",
  "packing": { "terminal_name": null, "terminal_code": null, "container_no": null, "loaded_by": null, "departure_note": "In the next 30 days" },
  "document_url": "https://api.lmnauto.com/v1/invoices/01J8.../document?version=1",
  "issued_at": "2026-09-02T19:49:00+09:00",
  "paid_at": null,
  "voided_at": null,
  "void_reason": null,
  "created_at": "2026-09-01T10:00:00+09:00",
  "updated_at": "2026-09-02T19:49:00+09:00"
}
```

A draft looks the same with `status: "draft"`, `number: null`, `version: 0`, `document_url: null`, `issued_at: null`, and possibly `consignee: null`, `shipment_month: null`, or `amounts.price: null` while LMN ops are still completing it.

### Errors

| Code                | HTTP | Condition                                                                                     |
| ------------------- | ---- | --------------------------------------------------------------------------------------------- |
| `invoice_not_found` | 404  | Unknown ID, or the invoice belongs to another partner or the other environment (never `403`). |

***

## GET /v1/invoices/\{invoice\_id}/document — PDF

```bash theme={null}
curl -H "x-api-key: $KEY" -o SKL_2026_09_001_v1.pdf \
  "https://api.lmnauto.com/v1/invoices/01J8.../document?version=1"
```

Streams the "COMMERCIAL INVOICE & PACKING LIST" PDF — `Content-Type: application/pdf`, `Content-Disposition: inline; filename="{number}_v{N}.pdf"`.

| Param     | Description                                                                                        |
| --------- | -------------------------------------------------------------------------------------------------- |
| `version` | Optional positive integer. The PDF published for that exact version. Omit for the current version. |

This is the **only** way to obtain the PDF: there are no signed or public URLs, and the route requires your API key like every other. Every published version keeps its own immutable PDF. Sandbox PDFs carry a diagonal `SANDBOX — NOT A TAX DOCUMENT` watermark. The route counts against the shared `/v1` per-key quota like every other call — store the bytes rather than re-downloading per page view.

### Errors

| Code                 | HTTP | Condition                                                                                  |
| -------------------- | ---- | ------------------------------------------------------------------------------------------ |
| `validation_error`   | 400  | `version` is not a positive integer.                                                       |
| `invoice_not_found`  | 404  | Unknown invoice, unknown `version`, or the invoice belongs to another partner/environment. |
| `invoice_not_issued` | 409  | The invoice is still a `draft` — no PDF exists yet.                                        |

***

## GET /v1/orders/\{id}/invoice — Invoice for an order

```bash theme={null}
curl -H "x-api-key: $KEY" https://api.lmnauto.com/v1/orders/01HXYZ.../invoice
```

Returns the order's newest invoice in any status (a draft as soon as the order is `secured`), same shape as `GET /v1/invoices/{invoice_id}`. For a quick existence/status check you don't need this call — read `invoice` on the order itself.

### Errors

| Code                | HTTP | Condition                                                                |
| ------------------- | ---- | ------------------------------------------------------------------------ |
| `order_not_found`   | 404  | Unknown order ID, or the order belongs to a different API key.           |
| `invoice_not_found` | 404  | The order exists but has no invoice (e.g. it has not reached `secured`). |

***

## Sandbox

Drive a sandbox order to `secured` with [`POST /v1/orders/{id}/sandbox-status`](/endpoints/status-updates) — LMN drafts the sandbox invoice the same way it does in production, and it shows up on the order and on these routes. Issuing is an LMN-side action in both environments; contact LMN to have a sandbox invoice issued so you can exercise the PDF route and the `invoice.issued` webhook end-to-end. Sandbox and production invoices are fully separate (numbers, PDFs, webhooks).