### Calendar-month tabular breakdowns

This section describes how to spread Archera premiums, rebates, savings, and commitment costs across accounts, services, or child orgs.

### List available allocation reports

**Endpoint:**  `get/beta/v1/org/{org_id}/allocation-reports`

Catalog of allocation/showback reports a caller can fetch via `GET /allocation-reports/<report_type>`. Each entry declares the query parameters it accepts and the columns its rows will contain.

#### Path parameters
- `org_id` (string, uuid) **Required**

#### Responses
- **200 OK** 
  - Content-Type: application/json
  - **Fields:**
    - `report_type` (string) **Optional**
    - `name` (string) **Optional**
    - `description` (string) **Optional**
    - `category` (string) **Optional**
    - `row_grain` (string) **Optional**
    - `update_cadence` (string) **Optional**
    - `params` (Array of AllocationReportParamDescriptor) **Optional**
    - `output_fields` (Array of AllocationReportFieldDescriptor) **Optional**

- **400 Bad request** 
- **401 Unauthorized** 
- **403 Forbidden** 
- **404 Not found** 
- **405 Method not allowed** 
- **409 Conflict** 
- **500 Internal server error** 
- **Default** : 
  - Content-Type: application/json

### Fetch one allocation report

**Endpoint:**  `get/beta/v1/org/{org_id}/allocation-reports/{report_type}`

Returns one report's rows for the requested calendar month. Accepted query parameters and returned columns vary by `report_type` — call the list endpoint to discover them. Pass `?format=csv` for a CSV download (default is JSON).

#### Path parameters
- `org_id` (string, uuid) **Required**
- `report_type` (string) **Required**

#### Responses
- **400 Bad request** 
  - Example Response:
    ```json
    {
      "message": "text",
      "detail": null,
      "code": "text",
      "url": "text",
      "timestamp": "text",
      "type": "text"
    }
    ```
- **401 Unauthorized** 
- **403 Forbidden** 
- **404 Not found** 
- **405 Method not allowed** 
- **409 Conflict** 
- **500 Internal server error** 
- **Default** : 
  - Content-Type: application/json

### List periods available for an allocation report

**Endpoint:** `get/beta/v1/org/{org_id}/allocation-reports/{report_type}/periods`

Returns the (year, month) periods this report can be queried for, given the supplied filter params. Each entry has `status: "finalized"` for past months backed by an invoice, or `"in_progress"` for the current calendar month when the report's `update_cadence` is "daily".

#### Path parameters
- `org_id` (string, uuid) **Required**
- `report_type` (string) **Required**

### HTTP Request Examples

```http
GET /beta/v1/org/{org_id}/allocation-reports HTTP/1.1
Accept: */*
```

```http
GET /beta/v1/org/{org_id}/allocation-reports/{report_type} HTTP/1.1
Accept: */*
```

```http
GET /beta/v1/org/{org_id}/allocation-reports/{report_type}/periods HTTP/1.1
Accept: */*
```