> This page is for version V1 (default).
> For other versions, use one of these documentation indexes:
> - V1 (default): https://docs.ottimate.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ottimate.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ottimate.com/_mcp/server.

# Invoices

### Creating an Invoice

This shows how to create a new invoice with line items and mappings.

```python
# main.py

new_invoice = client.invoices.post_invoices_root(
    upload_id=f"SDK-INV-{time_now}",
    invoice_number=f"INV-{time_now}",
    ottimate_location_id=ottimate_location_id,
    ottimate_vendor_id=ottimate_vendor_id,
    total_amount=150.0,
    total_tax=15.0,
    items=[{"name": "SDK Item", "quantity": 1, "price": 150.0, "mappings": {"DEPARTMENT": ottimate_dimension_id }}],
)
ottimate_invoice_id = new_invoice.id
```

### Fetching an Invoice

This demonstrates how to retrieve an invoice by its ID.

```python
# main.py

fetched_invoice = client.invoices.get_invoices_id(id=ottimate_invoice_id)
```

### Fetching Invoices by Status

You can also retrieve a list of invoices that match a specific status.

```python
# Fetch invoices that are ready-for-export
invoices_response = client.invoices.get_invoices_root(
    status="ready-for-export",
    ottimate_location_ids=ottimate_location_id,
)
for invoice in invoices_response.results:
    print(f" - Ottimate Invoice ID: {invoice.id}, Number: {invoice.invoice_number}, Status: {invoice.status}")
```

### Updating an Invoice

This shows how to modify an existing invoice, such as updating a line item's quantity.

```python
# main.py

updated_quantity = 15

updated_invoice = client.invoices.patch_invoices_id(
    id=ottimate_invoice_id,            
    items=[{"id": invoice_item.get("line"), "quantity": updated_quantity}]
)
```

### Approving an Invoice

This shows how to approve an invoice that is pending approval.

```python
# main.py

approve_response = client.invoices.post_invoices_id_approve(id=ottimate_invoice_id)
print("Approve response:", approve_response.message)
```

### Flagging an Invoice

This shows how to flag an invoice for review with a reason.

```python
# main.py

client.invoices.post_invoices_id_flag(id=ottimate_invoice_id, flagging_reason="Needs review")
```

### Marking Invoices as Exported

You can mark one or more invoices as exported. This is useful when you have processed them in your external system.

```python
# Mark invoices as Exported
result = client.invoices.post_invoices_mark_exported(invoices=[{"invoice_id": <ottimate_invoice_id>, "marked_reason": "Exported via SDK"}])
print(f"✅ Marked invoices as exported: {result}")
```