# Client adjustments — minimum UI and data plan

**15 October 2026 · ODI-1438 · Proposed for Product review**  
The prototype UI is updated. Application data and financial integration are not implemented.

## One workflow

**Paid Invoice → Record adjustment → amount + handling choice → Save.**

- **Money returned:** record a refund already made outside Odia.
- **Keep as credit:** retain the agreed amount for that contact to use on a later Invoice.
- Optional related billed service, date and reason. Completed and canceled services use the same form; their statuses stay unchanged.

For this MVP, credit originates from a paid Invoice. It is used to settle another Invoice for the same contact and currency. General promotional credit, transfers, currency conversion and paying out unused credit are outside scope.

## Minimum UI

| Location | Addition |
|---|---|
| Source paid Invoice | Record adjustment and compact dated records. Same action in its Journey Invoice-row menu. |
| Shared dialog | Amount, Money returned / Keep as credit, optional service, date, reason. |
| Contact Overview | Available credit and its history. Credit-note detail stays accessible here. |
| Receiving Invoice → Payment | Credit applied, reference, remaining amount due, Apply credit and Remove credit. History is a collapsed disclosure. |
| Existing Financials / Analytics | Existing metrics consume the adjusted values. No new cards, service lists, tab or dashboard. |

**Prototype change:** removed View credit note from the receiving Invoice and removed its large separate Credit history card. Payment now carries the minimal indication and an optional history disclosure.

## Connect services and Invoices — 18 October proposal

Keep one adjustment record and one shared form, with two contextual entry points:

- **Invoice … → Record adjustment:** choose an optional billed service.
- **Existing service-row … → Record adjustment:** preselect that service and its eligible paid Invoice. Ask for an Invoice only when several are eligible; if none exists, link to Invoicing rather than create an unsupported record.
- After saving, show the same compact amount/reference on the service and source Invoice. Do not add another service list or duplicate financial records. Whole-Invoice adjustments do not invent a service allocation.
- In the form, show service status and existing Include/Exclude choice as context. Their existing editors remain the owners of changes.

This keeps three related facts clear: **status = what happened; financial inclusion = what counts in Journey figures; adjustment = value returned or retained as credit.** Cancellation does not automatically create a refund; completed services can also have adjustments.

The source Invoice remains the billing/credit anchor. The service is the operational entry point and association. This service shortcut and compact linked summary are proposed for Product review; only the Invoice popover/table correction is implemented in this revision.

## Minimum data: two records

| Record | Proposed fields |
|---|---|
| **Client adjustment** | ID, tenant, source Invoice/Journey, contact, positive amount in cents, currency/base-currency snapshot, handling (refund or client credit), optional Trip Service, date, reason, author, void history. |
| **Credit application** | ID, tenant, parent adjustment, receiving Invoice, positive amount in cents, application date/author, reversal history. |

Source details and billed allowance come from the saved Invoice. Reuse existing FX conventions; do not change saved amounts when exchange rates move. Journey ownership may be derived from the Invoice rather than duplicated.

- **Available credit = issued credit − active applications.** Derive this balance and its status rather than storing another mutable total.
- **Amount due = Invoice total − payments received − applied credit.** Credit is separate from cash received.
- A refund has no credit applications. Two records can split an agreement between money returned and credit, within the same remaining source allowance.
- Void a mistaken record and retain history. Used credit must first be removed from its receiving Invoice. Apply/remove/void must be atomic to prevent concurrent double spending.

## How Financials should work

**Current source:** the engine and Analytics calculate from services and the shared Financial Health fold. They do not yet consume these client-adjustment records. The prototype still leaves Journey financial metrics unchanged.

**Recommendation:** giving value back against an included original sale reduces its original Journey revenue once, whether money is returned or kept as credit. Applying that credit later only settles the receiving Invoice.

| Event | Original Journey | Later Invoice |
|---|---|---|
| Record €600 refund | Revenue/margin fall €600, holding costs and commissions constant. Record money returned; preserve the original receipt. | No credit available. |
| Issue €600 credit against that sale | Same €600 reduction; €600 becomes available credit. No cash refund. | Can use the available balance. |
| Apply €400 credit later | No second revenue/margin reduction; €200 credit remains. | Amount due falls €400. Its service sales and margin stay unchanged. |

**Example:** €4,200 revenue − €2,800 cost − €420 TA Commission = €980 margin. A €600 refund **or** credit issued against this sale gives €3,600 net revenue and €380 margin. Applying €400 to a later €3,000 Invoice leaves €2,600 to pay; that Invoice's sale stays €3,000.

Supplier costs, Supplier Commission Earned, TA Commission and agent splits retain their existing owners. No automatic supplier recovery or commission recalculation is implied. An agreed change to those amounts is managed separately.

## Cancellation: avoid counting a reduction twice

Existing Exclude removes the canceled service's whole sale, cost and sale commission. The smallest proposed policy is:

- A linked adjustment follows its source service's financial inclusion. If excluded, both the sale and its adjustment are outside on-book margin. The refund record and available credit still exist.
- For a partial refund with retained value/costs, keep the service **Included**. A €900 sale, €600 cost, €90 commission and €200 refund gives €700 net revenue and €10 margin.
- When an Invoice mixes included and excluded services, require Related service in the existing picker. Allow an unallocated whole-Invoice adjustment when all billed services are included. This avoids inventing an allocation table or guessing the financial effect.

This is a proposed integration rule, not implemented in the prototype. No automatic status/treatment changes or new treatment lock are proposed.

## Smallest implementation boundary

1. Add the two records through existing repositories, tenant permissions/RLS and saved Invoice data. Enforce shared source caps, same contact/currency, available balance, different receiving Invoice and unpaid balance.
2. Add one shared adjustment policy at the existing Journey calculation-input boundary. Feed adjusted revenue/gross-margin components into the canonical Financial Health fold. Preserve selling-price and commission formulas; do not create synthetic Trip Services.
3. Feed those same components into Analytics, including service attribution, unallocated totals, margin percentages and Total Earnings. Apply the source Journey's existing reporting-period/filter convention; keep event dates in record history. Invoice balance, settled/outstanding totals and existing Invoice outputs must count applied credit as settlement, separately from cash collected. A refund does not reopen the original paid Invoice.

Verify refunds/issued credit/application separately, completed/canceled services, inclusion changes, corrections, concurrency, FX snapshots and Journey/Analytics parity. New reads require the existing local benchmark gate. Correct Invoice balances alone do not prove correct margins.

**Decision to approve before implementation:** both refund and credit issuance adjust the source sale once, with the financial-inclusion rule above. Tax-document PDFs, bank execution and accounting-period cashflow reporting stay outside this MVP.

## Source evidence

Checked 15 October: `FinancialCalculationService.ts` (inclusion/totals), `derive-proposal-financials.ts` (Journey orchestration), `packages/odia-supa/src/financial-health.ts` (shared fold), `financialAnalyticsRepository.ts` (Analytics inputs), `updateServiceFinancialTreatment.ts` (existing treatment), and Invoice line-price/currency snapshots in `types/invoice.ts`.

[Stripe's credit-note model](https://docs.stripe.com/invoicing/dashboard/credit-notes) also separates correcting a paid Invoice from returning cash or retaining customer credit. This is a product-model reference, not a proposal to integrate Stripe or issue formal tax documents.