vitna.ai/docs/api/v1/engine/reconcile Machine view
Raw .md llms.txt
> Source: https://vitna.ai/docs/api/v1/engine/reconcile
> Raw Markdown: https://vitna.ai/docs/api/v1/engine/reconcile.md
> Corpus index: https://vitna.ai/llms.txt

# Stateless invoice reconciliation

Reconcile a usage window and optional stated vendor invoice lines against historical Witness list-price periods in memory, deriving exact list-cost bounds and implied enterprise discounts with zero retention.

```
POST /api/v1/reconcile
```

```bash
curl -X POST https://vitna.ai/api/v1/reconcile \
  -H "content-type: application/json" \
  -d '{
    "window": "2026-10-01..2026-10-31",
    "unitProfile": {
      "inputTokensPerUnit": 2000,
      "outputTokensPerUnit": 500
    },
    "readings": [
      { "sku": "openai/gpt-5.6-luna", "units": 100000 }
    ],
    "spend": [
      { "amountUsd": 85.00 }
    ]
  }'
```

## Zero retention over confidential bills

`POST /api/v1/reconcile` requires no API key and stores nothing (`Cache-Control: no-store`). Historical list prices are read from `witness.price_period` across `window`; stated `spend` lines (`sku` omitted or `null` for whole-window invoice totals, or naming one SKU) are compared against the derived list bound to report `impliedDiscountPct` (negative when billed above public list).

If a price moved mid-window without daily usage granularity, `listCostUsd` and `impliedDiscountPct` report `[minUsd, maxUsd]` bounds rather than inventing an intra-month traffic split.

A window the record does not hold a price across, end to end, answers `200` with `"reconcilable": false` and a `reason`, never a guessed cost. The example's model was first priced on 2026-08-21, so August 2026 is not reconcilable for it and October is.

## Response shape

```json
{
  "reconciliation": {
    "reconcilable": true,
    "window": {
      "start": "2026-10-01",
      "end": "2026-10-31",
      "units": 100000,
      "sourceRef": "stateless-api",
      "importedAt": null
    },
    "rows": [
      {
        "skuId": "openai/gpt-5.6-luna",
        "units": 100000,
        "sharePct": 100,
        "priced": true,
        "periodIds": [13, 14],
        "moves": 0,
        "listPerUnit": { "minUsd": 0.001, "maxUsd": 0.001, "exact": true },
        "listCostUsd": { "minUsd": 100, "maxUsd": 100, "exact": true },
        "successRate": null,
        "listPerSuccessfulUnit": null
      }
    ],
    "pricedUnits": 100000,
    "unpricedUnits": 0,
    "coveragePct": 100,
    "listCostUsd": { "minUsd": 100, "maxUsd": 100, "exact": true },
    "moves": 0,
    "spend": [
      {
        "skuId": null,
        "amountUsd": 85,
        "comparable": true,
        "listUsd": { "minUsd": 100, "maxUsd": 100, "exact": true },
        "impliedDiscountPct": { "minUsd": 15, "maxUsd": 15, "exact": true }
      }
    ]
  },
  "sentence": "At list, the 100,000 priced units of this window cost $100.00, covering every unit that ran. The stated spend of $85.00 implies a discount of 15 percent off list.",
  "caveats": [
    "List prices only: what was actually paid is whatever the bill says. A supplied spend line is compared here and stored nowhere.",
    "Cost only, where no production success rate is recorded at or before the window's end. Cost per successful unit is derived only from a measurement somebody entered, never assumed at 100."
  ],
  "privacy": "Reconciled in memory with zero retention; supplied vendor invoice lines and usage counts are never stored.",
  "meta": {
    "generatedAt": "2026-11-16T07:17:47.025Z",
    "source": "database",
    "count": 1
  }
}
```
Human Machine Shift+M