Vouchers and gift cards

Quick reference

• Voucher list at /vouchers with status filters (All, Active, Redeemed, Expired, Voided). Each voucher detail page is at /vouchers/<id>.
• Issue from New voucher — set the amount, optionally a custom code (otherwise auto-generated as GV-XXXXXXXX), recipient name and email, expiry date, notes.
• Codes are uppercase alphanumeric with I / 1 / O / 0 excluded to avoid ambiguity over the phone. Eight random characters following the GV- prefix.
• Issuing a voucher requires the create_invoices permission — same as refunds, since you're creating a spendable money instrument.
• Redemption: from the POS payment modal's Voucher tab (full redemption — voucher balance ≥ sale total) or Split tab's voucher+card / voucher+cash modes (partial redemption — voucher covers some, customer pays the difference).
• Voucher balance is tracked atomically. Partial redemption decrements the balance; the voucher stays active until balance hits zero, at which point it flips to redeemed as a terminal state.
• Expiry is checked at lookup — an expired voucher rejects with “Voucher has expired” even if its status is still active in the database (status auto-transition on expiry isn't shipped; the check happens at use time).

Walkthrough

1. Issue a voucher

Open /vouchers and click New voucher top-right. The form has six fields: Amount (required), Custom code (optional — auto-generated if blank), Recipient name, Recipient email, Expiry date, Notes.

Amount must be greater than zero. The custom code, if provided, is converted to uppercase; if the code collides with an existing voucher at your tenant, the system silently falls back to an auto-generated code (no error — the form submits and the voucher gets a fresh code).

Recipient name and email are optional but worth filling — if the recipient email is on file, the voucher detail page surfaces an Email voucher button that sends a formatted email with the code and balance via Resend. Expiry date is also optional; without one the voucher never expires.

Click Issue voucher. The form posts; you land on the new voucher's detail page at /vouchers/<id> with the code displayed in monospace, the balance, the status (Active), and the expiry.

2. Email the voucher to the customer

From the voucher detail page, click Email voucher — the button only renders if a recipient email is on the voucher. The email is sent via Resend with your business name and a styled card containing the voucher code (monospace, large), the balance, and the expiry date. The action toasts “Voucher emailed to customer” on success.

For customers who walk out with a printed gift card or handwritten receipt, skip the email — the code is what matters. They present the code at redemption.

3. Redeem at the POS — full redemption

The customer arrives to spend the voucher. Build the cart at the POS as you would for any sale (see processing a sale), click Charge, switch to the Voucher tab in the payment modal.

Type or paste the voucher code (the input is auto-uppercased and styled monospace), click Look up. The modal calls the lookup API which checks: voucher exists at this tenant, status is active, expiry hasn't passed, balance > 0. Any failure surfaces as a clear error; “Voucher not found”, “Voucher is redeemed”, “Voucher has expired”, or “Voucher has no remaining balance”.

On success the modal shows the code and the remaining balance in a green card. If the balance is greater than or equal to the cart total, the Redeem voucher button activates. Click it; the server-side saga debits the voucher atomically, records a redemption row in gift_voucher_redemptions linked to the sale, and completes the sale through the same path as any other payment method. The success screen shows the sale number.

4. Redeem at the POS — partial / split redemption

If the voucher balance is less than the cart total, the Voucher tab hints to use a split. Switch to the Split tab and pick Voucher + Card or Voucher + Cash from the mode toggle.

Type the voucher code, click Look up; on success the modal shows the balance and pre-fills the remaining amount field with (total − min(voucher balance, total)). The remaining can be paid by card or cash depending on the mode. Confirm the amounts; click Complete split payment.

The server clamps the voucher amount to min(balance, total) — a $500 voucher applied to a $300 sale only debits $300, and the customer keeps the remaining $200 on the voucher. The voucher stays active; subsequent redemptions can draw against the remaining balance.

5. Manual redemption (phone-in, outside the POS)

From the voucher detail page's action stack, click Redeem manually — useful for redemptions outside a POS sale (e.g. a customer phones to apply voucher value to an outstanding invoice, or you're running an in-store credit adjustment). The form takes an amount and notes; click confirm. The voucher balance debits atomically via the same redeem_voucher RPC the POS uses, a redemption row is logged with sale_id = NULL and your notes. The detail page updates with the new balance.

6. Voiding a voucher

Sometimes a voucher needs to be cancelled — issued in error, fraud detected, customer wants their money back as cash and we're cancelling the voucher to avoid double-issuing. From the voucher detail page, click Void voucher; confirm in the modal. The status flips to voided and any future lookup attempts reject with “Voucher is voided.”

Void is a terminal state — a voided voucher can't be un-voided. If you need to put the value back into customer-spendable form, issue a fresh voucher or add the equivalent to store credit. Void is gated by the same create_invoices permission as issuance.

Common questions

Troubleshooting