# Wholesale Completion API

Business endpoints require an authenticated, ACTIVE `business_customer`; organization identity is never accepted from the request.

## Business account

- `GET /api/v1/business/dashboard`
- `GET /api/v1/business/credit`
- `POST /api/v1/business/orders/:id/use-credit` with `Idempotency-Key`
- `GET /api/v1/business/settlements`, `GET /api/v1/business/settlements/:id`
- `GET /api/v1/business/orders/recent`

The dashboard uses paid Order snapshots for monthly/lifetime volume and discounts, existing BusinessTier for classification, the immutable credit ledger for utilization, and settlement records for next payment information.

## Administration

- `POST /admin/wholesale/credit/transactions` (`wholesale.credit.manage`)
- `GET /admin/wholesale/businesses/:businessId/credit` (`wholesale.credit.read`)
- Settlement list/generation/issue/mark-paid endpoints with settlement permissions.

Credit formula: `available = creditLimit - ledger balance`. Captures/authorizations increase utilization; payment, release, and refund entries decrease it. Every operation locks the existing BusinessCreditAccount, validates ACTIVE business/account status and currency, and uses a unique event ID. Credit-backed Order placement atomically captures credit, consumes reservations, records an INTERNAL_CREDIT Payment, marks the Order paid, and reuses invoice issuance.

Settlements snapshot ledger activity for a unique business/period. Due dates come from the existing SettlementTerm. Numbers use ReferenceNumber, and only explicit lifecycle actions are accepted.

Payment allocation storage exists as a foundation. External bank matching, general ledger, ERP, tax-authority integration, and document-worker validation remain outside this phase.