Processing a refund

Quick reference

• Refunds live at /refunds as a status-filtered list (Pending, Approved, Rejected, Processed, Voided). Each refund detail page is at /refunds/<id>.
• Two entry points: open a sale at /sales and click Process refund, or use the Refund button on the POS top bar to look up the original sale by receipt number.
• Refunds are money-moving — the action requires the create_invoices permission. Default staff role has it; tenants who want manager-only refunds can change that in /settings/permissions.
• Sales older than 30 days require a manager PIN. The modal prompts for the PIN automatically; if the staff member doesn't have a PIN set, they're routed to set one first in settings.
• On completion: a refund row is written, inventory is restocked for any line marked Restock, payment reverses (store credit goes back to balance; cash and card are recorded as “refund issued via original method”), the parent sale flips to Refunded only if the full amount was refunded — partial refunds leave the sale active.
• A processed refund can be voided. The void reverses the restock and the store-credit issued, then flips the refund to Voided. Use sparingly — it's an audit event, not a free undo.

Walkthrough

1. Find the original sale

Two paths. From the sale: open /sales, find the row by sale number or customer name, click into the detail page. From the POS: click the Refund button at the top of the product grid — a modal opens with a receipt-number search. Type or paste the receipt number, click Find.

The POS refund modal is a one-pager — find sale, select items, process — useful for over-the-counter quick refunds against a recent sale. The sale-detail refund modal is the same underlying flow with a slightly fuller surface (item-by-item quantity controls, notes, refund-method picker per item). Both lead to the same refund row.

2. Pick what to refund

The sale's line items render with a per-line quantity control — default 0 (nothing selected). For a full refund, set each line to its full sold quantity (the POS modal pre-fills these). For a partial refund — customer keeps two earrings, returns one — set the line quantity to 1.

The running refund total recomputes as you adjust quantities. The server-side bound check guarantees the refund total can't exceed the original sale's remaining refundable amount (sale subtotal minus already-refunded), so even a misclick or an aggressive intervening browser can't over-refund.

3. Pick the refund method

Three options in the selector:

• Original payment method — the refund is recorded as having been returned through whatever payment method the original sale used (card → card refund, cash → cash returned, voucher → voucher reactivated). For card, you may also need to issue the actual refund through your payment terminal — Nexpura records the result; the physical money movement is on the terminal side unless Stripe is connected and configured for refunds.
• Store credit — the refund amount is added to the customer's store-credit balance instead of returning cash. Customer must be on file; the modal errors out if the original sale was a walk-in with no customer attached.
• Cash — refund issued as cash from the till, regardless of how the customer originally paid. Useful when a customer paid card but wants cash back, or when the original payment method isn't available (e.g. a voucher that's expired).

4. Pick a reason and add notes

The reason selector has five options: Customer changed mind, Defective / damaged item, Wrong item received, Quality issue, Other. Pick the closest match. Notes is a free-text field — useful for “chip on the inside band, jeweller confirmed manufacturing defect” or “customer returning earring set bought as gift; receipt brought in by recipient”. Reason + notes show on the refund detail page and the audit log.

5. The manager-PIN check on older sales

Click Process refund. If the original sale was created less than 30 days ago, the refund runs immediately. If the sale is older than 30 days, the action returns a “manager PIN required” error and a PIN modal opens.

One of two modes. Verify — you already have a PIN set: type the four-digit PIN, click confirm, the refund re-runs with the verified PIN. Set — you don't have a PIN on file yet: the modal walks you through setting one (PIN + Confirm PIN), then proceeds with the refund. PINs live on the team-member record and are checked against the calling user's own PIN — staff verify their own, not someone else's.

If you cancel the PIN modal, the refund modal stays open with a hint: “Refund cancelled — manager PIN is required to refund a sale older than 30 days.” Nothing is committed.

6. Refund processes — what runs server-side

On commit, the server runs the whole motion atomically (via the process_refund_v2 RPC on tenants with the new money-correctness flag; the legacy path is functionally equivalent):

• Refund row written — with a next-sequential refund number (RF-0042, RF-0043, …), the reason, the method, the refund total, and a link back to the original sale.
• Refund items inserted — one row per refunded line with the quantity, unit price, and a Restock flag (defaults true for any line with an inventory ID; false for service / labour lines that don't map to stock).
• Stock restocked — for every restocked line, a stock_movements row is inserted with type return and positive quantity. The DB trigger applies the movement to inventory.quantity. The piece is back on the floor.
• Payment reversed — for store credit, the customer's balance is incremented atomically (with a history row in customer_store_credit_history tagged with the refund ID). For cash and original-method, the refund row records the disposition; the physical money movement happens off-system.
• Parent sale flipped (only if fully refunded) — if the refund + any prior refunds against this sale add up to the full sale subtotal, the original sale's status flips to refunded and shows as such on the sales list. Partial refunds leave the sale on its prior status and let further partial refunds run against the remaining value.

7. Print or download the refund receipt

On the refund detail page, the top-right action stack has Download which opens the refund PDF in a new tab — formatted like a tax invoice with a negative total and the refund-method line. Print or email to the customer as needed; the receipt is generated on demand, so any later change (e.g. void) is reflected the next time it's opened.

8. Voiding a refund (if needed)

Sometimes a refund is issued in error. From the refund detail page, click Void refund and confirm the modal warning. The void reverses the side effects: compensating stock movements deduct the restocked inventory back; store credit issued is decremented from the customer's balance; the parent sale flips back from refunded to its prior state (paid or completed) unless another active refund still applies to it. The refund row itself stays — flipped to voided — so the audit trail shows what was issued and then reversed.

Void is gated by the same create_invoices permission as the original refund. A voided refund is a terminal state — no further actions, no re-activate.

Common questions

Troubleshooting