---
title: "Usage Chargeback & Settlement"
url: "https://nexora.apim.eu/apis/chargeback-settlement/versions/109ed889-6e58-4a7d-be59-d2717eab4852"
---

# Usage Chargeback & Settlement

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Usage Chargeback & Settlement","version":"1.0.0","description":"Settles the usage chargeback after a billing period closes: create a\nsettlement, retrieve the invoice, record incoming cost-center payments.\n\nThe chargeback rate is set per business unit under the platform's\ninternal cost-allocation policy. For a heavily subsidized deployment -\nsuch as a pilot funded partly from the shared platform budget - the\nconsuming team's rate typically must not exceed the unit's approved\nceiling. The API validates the rate against that ceiling when a\nsettlement is created.\n","contact":{"name":"API Support - Nexora AI","email":"api-support@nexora.example"},"license":{"name":"For demonstration purposes only"}},"servers":[{"url":"https://api.nexora.example/v1","description":"Production"},{"url":"https://sandbox.api.nexora.example/v1","description":"Sandbox"}],"tags":[{"name":"Settlements"},{"name":"Invoices"},{"name":"Chargeback"}],"security":[{"apiKey":[]}],"paths":{"/settlements":{"get":{"tags":["Settlements"],"summary":"List settlements","operationId":"listSettlements","parameters":[{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/SettlementStatus"}},{"name":"agent_id","in":"query","schema":{"type":"string","example":"agt_8f2c1a"}},{"name":"period_from","in":"query","schema":{"type":"string","format":"date"}},{"name":"period_to","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Results list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Settlement"}},"page":{"$ref":"#/components/schemas/Page"}}}}}},"401":{"$ref":"#/components/responses/NotAuthenticated"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"tags":["Settlements"],"summary":"Create a settlement","description":"Creates the settlement for a completed billing period. The basis is\nthe metered usage cost for that period.\n","operationId":"createSettlement","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementCreate"},"example":{"agent_id":"agt_8f2c1a","usage_type":"standard","billing_basis_usd":6380,"chargeback_rate_percent":12,"period_end_date":"2026-08-31","cost_center":{"name":"Customer Success","cost_center_id":"CC-4021","business_unit":"Support Engineering"}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Settlement"},"example":{"id":"stl_7c53","agent_id":"agt_8f2c1a","status":"open","usage_type":"standard","billing_basis_usd":6380,"line_items":[{"payer":"consuming_team","rate_percent":12,"net_usd":765.6,"overhead_usd":61.25,"total_usd":826.85}],"due_date":"2026-09-14"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/NotAuthenticated"},"422":{"description":"Chargeback rate not permitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"chargeback_rate_not_permitted","message":"The chargeback rate exceeds the business unit's approved ceiling.","details":[{"field":"chargeback_rate_percent","reason":"exceeds_ceiling"}]}}}}}}},"/settlements/{settlementId}":{"parameters":[{"name":"settlementId","in":"path","required":true,"schema":{"type":"string","example":"stl_7c53"}}],"get":{"tags":["Settlements"],"summary":"Retrieve a settlement","operationId":"getSettlement","responses":{"200":{"description":"Settlement","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Settlement"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/settlements/{settlementId}/payments":{"parameters":[{"name":"settlementId","in":"path","required":true,"schema":{"type":"string","example":"stl_7c53"}}],"post":{"tags":["Settlements"],"summary":"Record a payment","description":"Partial transfers are allowed; the status only moves to `paid` once the balance is settled in full.","operationId":"recordPayment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_usd","value_date"],"properties":{"amount_usd":{"type":"number","format":"float","example":826.85},"value_date":{"type":"string","format":"date","example":"2026-09-10"},"reference":{"type":"string","example":"XFER-2026-0418"}}}}}},"responses":{"200":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Settlement"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/invoices/{invoiceId}/pdf":{"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"type":"string","example":"inv_a920"}}],"get":{"tags":["Invoices"],"summary":"Download an invoice as PDF","operationId":"downloadInvoicePdf","responses":{"200":{"description":"PDF document","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/chargeback/calculator":{"post":{"tags":["Chargeback"],"summary":"Calculate a chargeback upfront","description":"Runs a chargeback calculation without creating a settlement - useful\nfor budget conversations and for the figure shown in the catalog\nentry.\n","operationId":"calculateChargeback","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["billing_basis_usd","chargeback_rate_percent"],"properties":{"billing_basis_usd":{"type":"number","format":"float","example":6380},"chargeback_rate_percent":{"type":"number","format":"float","example":12},"overhead_percent":{"type":"number","format":"float","default":8}}}}}},"responses":{"200":{"description":"Calculation","content":{"application/json":{"schema":{"type":"object","properties":{"line_items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"total_usd":{"type":"number","format":"float","example":826.85}}}}}},"400":{"$ref":"#/components/responses/ValidationError"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"apikey","description":"Every call carries an API key in the `apikey` header. You generate the\nkey in the Nexora AI portal under \"My Apps\"; it's shown exactly once.\n\nEach key has the scopes it's allowed to use attached to it. If one is\nmissing, the API responds with `403` and `code: \"scope_missing\"`; the\nmissing scope is in `details[].field`.\n"}},"responses":{"NotAuthenticated":{"description":"Key is missing, revoked or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"The request doesn't match the schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Rate limit reached","headers":{"Retry-After":{"schema":{"type":"integer","example":12}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Page":{"type":"object","description":"Cursor-based pagination.","properties":{"count":{"type":"integer","example":25},"total":{"type":"integer","example":138},"next_cursor":{"type":"string","nullable":true,"example":"eyJzIjoyNX0"}}},"ErrorDetail":{"type":"object","properties":{"field":{"type":"string","example":"chargeback_rate_percent"},"reason":{"type":"string","example":"missing"}}},"Error":{"type":"object","description":"Uniform error format across all Nexora AI APIs.","required":["code","message"],"properties":{"code":{"type":"string","example":"validation_failed"},"message":{"type":"string","example":"The billing basis is required to calculate the chargeback."},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"SettlementStatus":{"type":"string","enum":["draft","open","partially_paid","paid","canceled"],"example":"open"},"UsageType":{"type":"string","enum":["standard","burst","reserved"],"example":"standard"},"CostCenter":{"type":"object","properties":{"name":{"type":"string","example":"Customer Success"},"cost_center_id":{"type":"string","example":"CC-4021"},"business_unit":{"type":"string","example":"Support Engineering"}}},"LineItem":{"type":"object","properties":{"payer":{"type":"string","enum":["consuming_team","platform_subsidy","partner_cost_center","shared_services"]},"rate_percent":{"type":"number","format":"float","example":12},"net_usd":{"type":"number","format":"float","example":765.6},"overhead_usd":{"type":"number","format":"float","example":61.25},"total_usd":{"type":"number","format":"float","example":826.85}}},"SettlementCreate":{"type":"object","required":["agent_id","usage_type","billing_basis_usd","chargeback_rate_percent","period_end_date"],"properties":{"agent_id":{"type":"string","example":"agt_8f2c1a"},"usage_type":{"$ref":"#/components/schemas/UsageType"},"billing_basis_usd":{"type":"number","format":"float","description":"Total metered usage cost for the billing period, before the chargeback rate is applied.","example":6380},"chargeback_rate_percent":{"type":"number","format":"float","example":12},"period_end_date":{"type":"string","format":"date","example":"2026-08-31"},"cost_center":{"$ref":"#/components/schemas/CostCenter"}}},"Settlement":{"type":"object","properties":{"id":{"type":"string","example":"stl_7c53"},"agent_id":{"type":"string","example":"agt_8f2c1a"},"status":{"$ref":"#/components/schemas/SettlementStatus"},"usage_type":{"$ref":"#/components/schemas/UsageType"},"billing_basis_usd":{"type":"number","format":"float","example":6380},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"invoice_id":{"type":"string","example":"inv_a920"},"due_date":{"type":"string","format":"date","example":"2026-09-14"},"paid_usd":{"type":"number","format":"float","example":0},"created_at":{"type":"string","format":"date-time","example":"2026-08-15T07:30:00Z"}}}}}}
```