# Generate monthly invoices

Generate invoices for all active organizations with usage for a specific month. This endpoint is restricted to staff users only and processes multiple organizations in a single request.

#### Request Body

**`year`** integer required

Year for billing period (2024-2100).

**`month`** integer required

Month for billing period (1-12).

## Returns

Returns a summary of the generation process including the number of invoices generated, failed, and details for each invoice or error.

### Response Fields

**`generated`** integer

Number of invoices successfully generated.

**`failed`** integer

Number of organizations that failed invoice generation.

**`invoices`** array

Array of successfully generated invoice objects (without items for brevity).

**`errors`** array

Array of error objects for failed generations, including organization ID and error message.


```bash
curl -X POST "https://api.aitronos.com/v1/invoices/generate-monthly" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "year": 2024,
    "month": 12
  }'
```


```python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.post(
    "https://api.aitronos.com/v1/invoices/generate-monthly",
    headers={"X-API-Key": api_key},
    json={
        "year": 2024,
        "month": 12
    }
)

result = response.json()
print(f"Generated: {result['generated']}, Failed: {result['failed']}")
```


```javascript
const response = await fetch(
  "https://api.aitronos.com/v1/invoices/generate-monthly",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.FREDDY_API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      year: 2024,
      month: 12
    })
  }
);

const result = await response.json();
console.log(`Generated: ${result.generated}, Failed: ${result.failed}`);
```

**Response:**

201 Created

```json
{
  "generated": 42,
  "failed": 1,
  "invoices": [
    {
      "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": null,
      "currency": "CHF",
      "exchange_rate": 1.0,
      "subtotal": 1250.50,
      "tax_rate": 0.081,
      "tax_amount": 101.29,
      "total_amount": 1351.79,
      "status": "issued",
      "items": [],
      "created_at": "2024-12-31T23:59:59Z",
      "updated_at": "2024-12-31T23:59:59Z"
    }
  ],
  "errors": [
    {
      "organization_id": "org_456e4567e89b12d3a456426614174000",
      "error": "No usage data found for period"
    }
  ]
}
```

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 create invoices",
    "type": "client_error",
    "status": 403,
    "details": {
      "required_role": "aitronos_staff"
    },
    "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 month or year",
    "system_message": "Validation error",
    "type": "client_error",
    "status": 422,
    "details": {
      "field": "month",
      "value": 13
    },
    "trace_id": "2fbbf3b6-51a1-4f1b-88e2-c00e8b52fbb8",
    "timestamp": "2025-11-26T08:21:45Z"
  }
}
```