A05 — Attributable creator payout history API

Status: blocked. Updated: 2026-09-06. Assigned agent: unassigned. Implementation PR: none.

Issues and acceptance covered

#51. The acceptance boundary is the implementation scope and completion checks below; see the issue acceptance matrix for parent coverage. Shared definitions: financial contract; proof anchors: evidence index.

Dependencies and blockers

A03 and #56–#59 operation/allocation/event contracts. D-05 legacy evidence limits. Coordinate A04 GET balance mount; provider money movement is owned outside this PR.

Repository and expected files

Backend: src/api/routes/payouts.ts GET /me or dedicated additive own-history router; proposed analytics payout history serializer/query/tests. Read payout-operation/allocation models and legacy Payout/PayoutItem.

Existing behavior and verified gap

Current /me returns last 50 rows with net amount/method/created/completed only. No pagination, per-campaign/submission allocation, gross/net/fee breakdown, or explicit unknown/released event coverage (E03/E06).

Proposed implementation boundary

Paginate operations using stable time+ID cursor; expose safely scoped allocation breakdown and chronological status events. Distinguish requested/reserved/processing/unknown/released/failed/paid through producer state. Known legacy operations remain labelled incomplete; missing completedAt is not inferred.

Expected API / data contract

Additive v2 history endpoint or envelope with items/cursor/summary, named gross/net/deductions, initiated/completed times, campaign/submission allocations, coverage. Existing /me 50-row contract remains usable; provider account IDs/full destinations stay private.

Required tests

Multi-campaign payment allocation 9+3, partial cycle/later growth, duplicate webhook history, unknown then success, failure release exactly once, undated completed legacy row, pagination ties and no duplicate operation totals, ownership/PII whitelist.

Suggested agent tier

Smart owner validates amount mapping/state/identity; lower-cost agent implements agreed serializers and pagination wiring.

Expected PR boundary and reason

One history-contract backend PR stacked on A03 and payout source interfaces. Unlocks A12; no eligibility or provider-dispatch change. Keep compatibility additive, avoid unrelated cleanup, and list exact stacked commits and later units unlocked in the PR. If observed scope grows beyond this boundary, update the plan before splitting or adding work.

RBAC requirements / TODOs

Preserve requireAuth and own operation scope. TODO(RBAC): Any staff reuse of history requires the approved cross-creator finance capability; the creator endpoint cannot return arbitrary creator IDs or provider-sensitive evidence.

Completion and reconciliation checks

History paid sum matches own paid positions only for matching basis/date/coverage. Campaign drilldowns sum allocations, not whole transfer amounts. Attempts/status events do not multiply payment totals.

Record actual tests, source schema/contract versions, PR/merge SHA, manual evidence and residual coverage before changing status to review/complete. Any unexpected migration must first satisfy the migration gates; never bundle upstream financial writer work into this analytics unit.