Returns and Settlement Batches

Return History and Settlement Batches are separate store-scoped audit views:

• Return History records returned products, refund results, and restock decisions. It requires store.returns.read.
• Settlement Batches records Peak Gateway card batches for the selected store. It requires store.transactions.read.

A return is an item and refund record. A settlement batch is a group of card transactions sent through Gateway. Do not use one as a substitute for the other during reconciliation.

Audit return history

1. Confirm the selected store.
2. Open Store Operations > Return History.
3. Review each row's Date, Product, Qty, Refund Amount, Refund Status, Restocked, and Reason.
4. Select a row to open Return Details.
5. Confirm:
   • the return ID and date;
   • reason and any notes;
   • quantity and whether the item was restocked;
   • refund amount and whether the refund is Completed, Pending, or Failed;
   • the product, customer, and staff member when recorded; and
   • the original transaction, refund transaction, or Gateway credit-note reference when present.
6. Use Open original transaction to compare the return with the sale. Use Open inventory item to review the returned product when a product link is available.
7. Use Previous and Next to continue through older records.

Return History is an audit page; it does not create or edit returns. Authorized users start a product return from an eligible transaction in Sales & Payments by selecting Return Items. That action requires return write access and transaction administrator access.

Submit a product return

Select all products and quantities, optionally enter a reason, and explicitly choose whether sellable items should be restocked. Create Return submits the entire selection as one durable return command. The server checks the original sale, remaining quantities, stored prices, discounts, deposits, and original tender allocations before admitting any item. Amount-only Food EBT refunds require the full remaining balance across the original tenders, including any cash portion; select items and quantities for a partial return. A partial amount-only Food EBT request is rejected before acceptance and leaves the remaining balance available.

Refunds include the dual-pricing card fee charged on the original sale. A full refund returns the full amount paid, including that fee. Product returns include the selected items' discounted price, tax, applicable deposits, and proportional share of the charged card fee. The server allocates rounded cents cumulatively so all returned quantities reconcile to the exact charged fee without exceeding it. Cash and non-dual-pricing sales do not acquire a card fee. Changing today's dual-pricing settings does not change a historical refund.

For split cash/card sales, cash already returned as change is not refundable. Historical gross-cash records deduct that change; versioned prepared-checkout records already store applied cash, so the server uses the durable checkout ticket to avoid deducting change a second time. The versioned checkout header is retained for as long as the matching sale exists, even after checkout operation and quote payloads expire, so older refundable sales keep the same cash interpretation.

The transaction refund dialog uses the server's remaining refundable balance for its default and maximum, rather than the original display total. Choose Full refund [amount] to replace a previously entered partial amount with that remaining balance, or enter a partial payout. An entered amount is the total customer payout, including its card-fee component; leaving it blank also requests the full remaining balance. Pending refunds and reserved returns consume that same balance. Mobile Android and iOS likewise offer explicit full and partial choices. The terminal's return review shows the server-priced selection before any card or cash operation.

The command has one identity and one linked refund attempt for the whole selection. Requested or Pending means the payment or physical handoff is not yet confirmed; it does not mean that the return failed or completed. Retry delivery of the same request rather than creating a replacement attempt after a connection error. Other transactions remain available while the server reconciles pending work. The browser retains the same delivery key and unchanged selection across connection errors and page reloads. Start a new return attempt is an explicit new operation, not a retry or cancellation of earlier work; the server still owns every previously accepted command and its reservations.

Cash payout instructions appear only after a fresh server admission for that command. Admission is one-way: status, history, reloads, duplicate admission requests, and uncertain acknowledgements never authorize another payout. If cash admission was already recorded, the recovery view is record-only; confirm an actual earlier handoff without paying cash again. The server does not assume cash was handed over merely because a return or admission request was accepted. Confirmed merchant cash is recorded as an independent financial fact at the original handoff acknowledgement time, retaining the original sale, store, staff actor, amount, and currency even if the electronic refund is declined or still uncertain. Store reports count that cash once; a later completed aggregate refund does not count its cash component again. A browser cash handoff does not invent a terminal, authenticated terminal session, or drawer attribution. Review required means the confirmed cash remains accounted for but the electronic refund needs review: do not pay cash again or replace the original command. Recovery preserves already-confirmed acknowledgements and their original clock. Restock and bottle-deposit effects occur once, only after all required refund and handoff evidence is confirmed; a partial financial outcome does not complete the stock return. Blind returns remain a separate workflow and do not borrow item allocations from an original sale.

Interrupted refund preparation

Once validation and any required approval have succeeded, the server durably records the original normalized request and its organization, store, staff actor, original sale, operation key, and return-command authority before creating the linked refund. The transaction-state sweep resumes an expired preparation under the same operation and intended refund ID, including when child creation committed but its acknowledgment was lost or the process stopped before submission. Nullable requested amounts remain nullable; the server does not reconstruct a request from the child balance.

Preparation recovery acquires the existing bounded operation lease. It never treats an unknown provider dispatch as a new preparation: submitted or uncertain outcomes stay with the existing refund reconciliation workflow. Recovery does not invent an operator, approval, cash handoff, or missing request.

Direct transaction refund submissions require an explicit delivery key. Their response and same-key status lookup expose the allocated refund ID, original transaction ID, original key, and attempt status even before a refund transaction exists. refund_preparing means the request was accepted and awaits child creation or recovery; the optional transaction is absent until that child exists. This is not a failed refund or permission to submit a replacement. After durable acceptance, the existing sale-scoped fence retains the original operation until it reaches a confirmed terminal outcome; a different key cannot overlap it. A malformed or ineligible request rejected before admission remains a rejection, not accepted pending work.

The migration adds nullable immutable intent storage without backfilling guessed requests. Older preparations can be resumed from an actual frozen accepted return command; an older preparation with neither that root nor exact accepted intent remains pending for review, with its original identity and reserved balance preserved.

Upgrading terminals with interrupted older returns

The upgrade reads both older encrypted-device return tables without interpreting or rewriting their raw evidence. Delivery is independent of operator sign-in. The authenticated terminal transfers the original table, row, operation and transaction bytes, including malformed or opaque payloads, to encrypted server custody. A local row is removed only after the server acknowledges ownership of that exact unchanged row and digest. A lost acknowledgement retains the same bytes for delivery again; it never starts another refund. Pending transfer prevents destructive reset or deprovisioning from discarding the evidence, but does not reserve a checkout or prevent a new sale.

Where canonical server records prove an older reservation, recovery retains its original reservation and return IDs, staff actor, currency, tender keys, accepted-cash marker and acknowledgement time, and completed stock/deposit identities. It may inquire about an already accepted financial child and finish the original records after definitive confirmation. It cannot authorize a new payout, reader operation, operator session or financial retry. Confirmed cash remains recorded once even when the original card leg was declined or has no linked child; do not pay it again. Such incomplete returns remain available for review rather than being reported as completed.

The terminal that uploads evidence is not proof of which terminal originally handled the return. Recovery needs the original accepted child or an exactly matching consumed cash approval to prove that historical terminal before adopting a financial command or completing stock/deposit work. Without that proof, encrypted custody and review remain server-owned, and the original cash marker still contributes once to the sale and store refund history at its original time. It does not acquire a terminal, drawer, operator session or new physical permission. Later canonical proof can unlock recovery under the same original identities.

Opaque, mismatched or not-yet-provable evidence remains in device-scoped server review without linking another store's transaction or treating imported client flags as financial authority. The device status endpoint exposes ownership and safe status, never the stored payload. Deploy the owned schema/grants, protected server storage and command owners before the migrated clients. Retain the server's configured data-protection key; do not reinstall or erase a terminal to clear interrupted evidence.

Review settlement batches

1. Confirm the selected store.
2. Open Store Operations > Settlement Batches.
3. Review Current batch first. It shows the current Gateway batch ID and status, or states that no current batch exists.
4. Review the historical table:
   • Opened and Closed show the batch period;
   • Gateway batch ID identifies the processor record;
   • Status shows whether the batch is open, closed, or failed;
   • Transactions shows the number of included payments; and
   • Total shows the batch amount.
5. Select a row for Batch Details. Confirm the Gateway merchant and location references, result code, message, transaction count, total, and timestamps.
6. Use Previous and Next to continue through history.

Peak Gateway is the authority for the current and historical batch state. A transaction's Settlement section in Sales & Payments links back to its batch when an identifier is available.

Close an open current batch

The page shows Close Current Batch only when the current batch is open and the role has both store.transactions.write and store.transactions.admin.

1. Confirm the selected store and current Gateway batch ID.
2. Select Close Current Batch.
3. Read the confirmation and select Confirm Close once.
4. Wait for the success result and refreshed current/history records.

Do not repeatedly start new close attempts while the first attempt is still resolving. Reopen or refresh the page and check the Gateway status before trying again.

Complete the two reviews

A return review is complete when the product, quantity, refund outcome, restock decision, and original-sale link agree. A settlement review is complete when the expected card transactions and total appear in the correct Gateway batch and the batch state matches the period being reconciled.

For sales-level payment and receipt detail, use Sales & Payments. For a batch that remains open or failed, follow Troubleshooting and include the store, batch ID, amount, time, and exact result message when contacting Peak Support.