# Update invoice status

Update the status of an invoice. Only staff users can perform this operation.

## Status Transitions

Valid status transitions:

- `draft` → `issued` → `paid`
- `draft` → `cancelled`
- `issued` → `overdue` (automatic)
- `issued` → `cancelled`
- `overdue` → `paid`
- `overdue` → `cancelled`


Invalid transitions will be rejected with a 422 error.

#### Path Parameters

**`invoice_id`** string required

Invoice ID (format: `inv_<uuid>`).

#### Request Body

**`status`** string required

New status. Valid values: `draft`, `issued`, `paid`, `overdue`, `cancelled`.

**`payment_date`** datetime optional

Payment date (required when status is `paid`). ISO 8601 format.

## Returns

Returns the updated invoice object with the new status and payment date (if applicable).


```bash
curl -X PATCH "https://api.aitronos.com/v1/invoices/inv_123e4567e89b12d3a456426614174000/status" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paid",
    "payment_date": "2025-01-15T10:30:00Z"
  }'
```


```python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]
invoice_id = "inv_123e4567e89b12d3a456426614174000"

response = requests.patch(
    f"https://api.aitronos.com/v1/invoices/{invoice_id}/status",
    headers={"X-API-Key": api_key},
    json={
        "status": "paid",
        "payment_date": "2025-01-15T10:30:00Z"
    }
)

invoice = response.json()
print(f"Invoice status updated to: {invoice['status']}")
```


```javascript
const invoiceId = "inv_123e4567e89b12d3a456426614174000";

const response = await fetch(
  `https://api.aitronos.com/v1/invoices/${invoiceId}/status`,
  {
    method: "PATCH",
    headers: {
      "X-API-Key": process.env.FREDDY_API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      status: "paid",
      payment_date: "2025-01-15T10:30:00Z"
    })
  }
);

const invoice = await response.json();
console.log(`Invoice status updated to: ${invoice.status}`);
```

**Response:**

200 OK

```json
{
  "id": "inv_123e4567e89b12d3a456426614174000",
  "invoice_number": "INV-2024-12-AIT-001",
  "organization_id": "org_123e4567e89b12d3a456426614174000",
  "organization_name": "Aitronos AG",
  "billing_period_start": "2024-12-01T00:00:00Z",
  "billing_period_end": "2025-01-01T00:00:00Z",
  "issue_date": "2024-12-31T23:59:59Z",
  "due_date": "2025-01-30T23:59:59Z",
  "payment_date": "2025-01-15T10:30:00Z",
  "currency": "CHF",
  "exchange_rate": 1.0,
  "subtotal": 1250.50,
  "tax_rate": 0.081,
  "tax_amount": 101.29,
  "total_amount": 1351.79,
  "status": "paid",
  "items": [],
  "created_at": "2024-12-31T23:59:59Z",
  "updated_at": "2025-01-15T10:30:00Z"
}
```

401 Unauthorized

```json
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication required",
    "system_message": "Missing or invalid authentication token",
    "type": "client_error",
    "status": 401,
    "details": {},
    "trace_id": "2fbbf3b6-51a1-4f1b-88e2-c00e8b52fbb8",
    "timestamp": "2025-11-26T08:21:45Z"
  }
}
```

403 Forbidden

```json
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You don't have permission to perform this action.",
    "system_message": "Only staff can update invoice status",
    "type": "client_error",
    "status": 403,
    "details": {
      "required_role": "aitronos_staff"
    },
    "trace_id": "2fbbf3b6-51a1-4f1b-88e2-c00e8b52fbb8",
    "timestamp": "2025-11-26T08:21:45Z"
  }
}
```

404 Not Found

```json
{
  "success": false,
  "error": {
    "code": "INVOICE_NOT_FOUND",
    "message": "Invoice not found",
    "system_message": "Invoice does not exist",
    "type": "client_error",
    "status": 404,
    "details": {
      "invoice_id": "inv_123e4567e89b12d3a456426614174000"
    },
    "trace_id": "2fbbf3b6-51a1-4f1b-88e2-c00e8b52fbb8",
    "timestamp": "2025-11-26T08:21:45Z"
  }
}
```

422 Unprocessable Entity

```json
{
  "success": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid status transition",
    "system_message": "Cannot transition from paid to issued",
    "type": "client_error",
    "status": 422,
    "details": {
      "current_status": "paid",
      "requested_status": "issued"
    },
    "trace_id": "2fbbf3b6-51a1-4f1b-88e2-c00e8b52fbb8",
    "timestamp": "2025-11-26T08:21:45Z"
  }
}
```