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

# Chargeback API

> Define allocation rules and pull chargeback reports from KOSTRA via the REST API.

# Chargeback API

The chargeback endpoints let you automate cost attribution: define how shared spend is split, and pull the resulting report for finance. All calls require the `x-optscale-token` header (see [Authentication](/api/authentication)).

## Allocation rules

Allocation rules describe how a shared cost is divided across target pools. KOSTRA supports three split methods — `equal`, `weighted`, and `proportional`.

### List allocation rules

```
GET /restapi/v2/organizations/{organization_id}/allocation_rules
```

Returns the allocation rules defined for the organization.

### Create an allocation rule

```
POST /restapi/v2/organizations/{organization_id}/allocation_rules
Content-Type: application/json
```

Create a rule specifying the shared cost it applies to, the target pools, and the allocation method. For a weighted split, include the weight for each target pool; for proportional, each pool's share tracks its own spend; for equal, the cost is divided evenly.

### Get, update, or delete a rule

```
GET    /restapi/v2/organizations/{organization_id}/allocation_rules/{rule_id}
PATCH  /restapi/v2/organizations/{organization_id}/allocation_rules/{rule_id}
DELETE /restapi/v2/organizations/{organization_id}/allocation_rules/{rule_id}
```

Retrieve a single rule, change its targets, weights, or method, or remove it. Rules take effect on subsequent chargeback reports.

## Chargeback report

```
GET /restapi/v2/organizations/{organization_id}/chargeback_report?start_date=<ts>&end_date=<ts>
```

Returns the chargeback attribution for the period, combining direct pool spend with each pool's allocated share of shared cost according to your allocation rules. `start_date` and `end_date` are Unix timestamps.

This is the endpoint to pull a monthly chargeback into a finance system or an internal billing process.

## Export pool expenses

```
GET /restapi/v2/pool_expenses_exports/{export_id}/xlsx
```

Downloads a spreadsheet export of pool expenses, giving finance a shareable, auditable breakdown outside KOSTRA.

## A monthly chargeback integration

1. Ensure your allocation rules reflect the current cost-sharing policy (create or `PATCH` as needed).
2. `GET .../chargeback_report` for the closed month.
3. Post the per-pool totals to your finance system, or export to a spreadsheet for review.

Because attribution depends on resources being assigned to pools, keep pool assignment complete for the numbers to be defensible — see [Organize Spend with Pools](/guides/organize-with-pools).

## Related pages

* [Cost & Recommendations API](/api/cost-and-recommendations)
* [Modernization API](/api/modernization)
* [Set Up Chargeback and Allocation](/guides/set-up-chargeback)