---
id: WF-PFM-LLM-009
title: Correct an organization's AI charges
trigger: Record a reasoned correction to monthly charges.
product_area: platform
module: llm
revision: 1
status: draft
design_intent: proposed
implementation_evidence: partially-observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
  - CAP-PFM-LLM-015
moves:
  - STATE-PFM-LLM-005
crosses:
  - SVC-PFM-LLM-llm
idempotency: Each accepted correction creates another record and audit; retry does not replay an earlier correction.
concurrency: >-
  The period update serializes movements, but refund eligibility is read before that update without a locking
  balance check. Concurrent refunds can therefore pass against the same prior charge.
hops:
  - 'n': 1
    actor_or_service: LLM usage API
    action: Authorize a closed correction body through the management route.
    anchor: 'services-platform:modules/llm/aws/api/llm-usage.routes.ts:createHqTenantLlmUsageAdjustment'
    seam: sync
    on_failure: 'Reject unauthorized, malformed or unknown-organization requests.'
    left_inconsistent: No correction is accepted.
    observer: API response and security audit history for committed control changes.
    provenance: observed
    source: 'services-platform:modules/llm/aws/api/llm-usage-api-mapper.ts:mapAdjustmentRequest'
  - 'n': 2
    actor_or_service: Correction service
    action: 'Validate signed amount, reason, target month, refund balance and any associated request.'
    anchor: 'services-platform:modules/llm/services/adjustments/adjust-allowance.ts:requireAdjustable'
    seam: sync
    on_failure: Return validation errors without writing.
    left_inconsistent: No correction or audit is recorded.
    observer: API response and security audit history for committed control changes.
    provenance: observed
    source: 'services-platform:modules/llm/services/adjustments/adjust-allowance.ts:requireAdjustable'
  - 'n': 3
    actor_or_service: Correction service and credit ledger
    action: >-
      Create a current period if necessary and commit the signed correction, floored charge totals and audit
      together.
    anchor: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:applyAllowanceAdjustment'
    seam: sync
    on_failure: Roll back all three effects if persistence or audit fails.
    left_inconsistent: >-
      A missing-current-period refund bypasses the balance check; successful corrections never evaluate
      crossings.
    observer: API response and security audit history for committed control changes.
    provenance: observed
    source: 'services-platform:modules/llm/services/adjustments/adjust-allowance.ts:adjustAllowance'
branches: []
waits: []
evidence:
  - >-
    services-platform at ad3f6a6: modules/llm/aws/api/llm-usage.routes.ts, llm-usage-api-mapper.ts;
    services/adjustments/adjust-allowance.ts; services/persistence/allowance-periods.ts;
    db/llm-allowance-adjustments.table.ts; docs/debt/llm-adjustment-idempotency.md; docs/llm.md#Adjustments.
controls: [TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-003, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Correct an organization's AI charges

## What It Does

The management-authorized correction retains signed values as a new fact rather than editing request history.

## The Flow

```mermaid
flowchart TD
  H1["Authorize a closed correction body through the management route."]
  H2["Validate signed amount, reason, target month, refund balance and any associated request."]
  H1 --> H2
  H3["Create a current period if necessary and commit the signed correction, floored charge totals and audit together."]
  H2 --> H3
```

Validate the target and any associated request, then commit correction, period totals and audit in one transaction.

## When Something Fails

Persistence failure rolls back together. Refund validation reads a prior balance and missing current periods bypass that check; resulting totals floor at zero. Corrections create no threshold notices.

## Open Design Questions

Preparation must address replay safety and refund validation under concurrent changes.