Skip to main content

​
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).

​
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.