Invoices

Why is overdue a four-step sequence instead of one configurable lead time?

Two non-obvious goals served at once. First, the four steps carry different tones — mild at day 1 is informational (“just a heads-up the due date has passed”), medium at day 7 is a reminder, high at day 14 is a second reminder with clearer escalation language, and final at day 30 names the action required. Collapsing into one toggle-with-lead-time would force one email body to span all four tones — too soft for day 30 or too alarming for day 1. Second, day-1 / day-7 / day-14 / day-30 is a sequence customers across hundreds of jewellers have internalised — the late-payment workflow on the customer side roughly tracks the same beats. Keeping the cadence stable means the customer experience is predictable and operators don't have to pick a custom cadence per invoice.

If your store needs a different cadence (a stricter 30-60-90 commercial-invoice rhythm, or a softer-than-default approach with a phone-call cadence layered in), the tenant-level opt-out is the cleanest answer — disable the auto-reminders and run your follow-ups by hand or via your accounting tool.

Why does the draft invoice show DRAFT-XXXXXXXX instead of an INV- number?

Two reasons that point the same direction. First, the INV- sequence is canonical — every sent invoice gets a consecutive number from a single counter on the tenants row. If drafts pre-allocated INV- numbers, abandoned drafts would leave gaps in the sequence (auditors flag gaps; jewellers worry that someone deleted an invoice). Reserving DRAFT-XXXXXXXX for the in-progress state means the INV- sequence is gap-free in practice — every issued INV- corresponds to an invoice that was actually sent. Second, the DRAFT prefix signals to the operator that this isn't live yet — a quick-glance distinction between “saved halfway through” and “sent to the customer.”

The upgrade happens atomically at mark-sent — the same server action that flips status to unpaid assigns the next INV- number and dispatches the email. The customer never sees the DRAFT placeholder on their received invoice.

Why can't I edit a sent invoice?

Because the customer has already received it. An invoice once sent is a record of what was communicated — editing it changes that record without the customer's knowledge. The right shape for “I need to fix this” is to void the original and issue a corrected replacement. The void preserves the audit trail (“here's what we sent first, here's what we sent instead”) and the corrected invoice carries a fresh INV- number. The customer sees the explicit substitution rather than a silent rewrite.

Drafts are different — they haven't been communicated, so editing is safe and the canonical workflow.

The Stripe payment link is missing from a sent invoice. What went wrong?

The Stripe link generation is non-fatal — if the Stripe call fails (rate limit, network blip, the tenant's Stripe account not yet connected), the invoice ships without the link and the failure is logged to Sentry. The customer can still pay by other methods documented in the email (bank transfer to the configured BSB + account, or in-person at the store). The missing-link failure is the only Stripe path that's expected occasionally; we don't consider it a hard error.

If a tenant's invoices consistently ship without payment links, the diagnosis is almost always the Stripe account connection at /settings/billing — verify the Stripe Connect handshake is complete. See billing and subscription for the Stripe-side setup walkthrough.

Why is amount_due a computed column rather than writable?

Because it's a derived figure — total minus amount_paid — and the only safe way to keep it consistent with the underlying columns is to derive it on every update. If amount_due were writable, a payment that updated amount_paid but forgot to update amount_due would leave the invoice listing the wrong outstanding figure on the /invoices KPIs. Database-side computation eliminates that class of bug — every read of amount_due is guaranteed to match the latest total and amount_paid.

On the application side this means callers set total and amount_paid only;amount_due is read-only. The action files carry the comment explicitly so contributors don't try to set it manually.

Customer reports they never received the overdue reminder I expected

Symptom: an invoice is past due by more than a day, the customer wasn't opted out, and they say no email arrived. Cause: one of three. Tenant-level opt-out is on (check overdue_reminders_enabled on the tenants row). The customer email on file is stale or has a typo. The customer's mail provider routed to spam. Fix: verify the customer email on the customer detail page, ask the customer to check spam. If the tenant opt-out is set unintentionally, flip it back on at /settings/business-profile; the next daily cron picks the invoice up. For a one-off manual reminder, the operator can currently re-email via the invoice detail page's Email Invoice action — that path is the same template the cron uses.

Recording a payment returns “Duplicate detected”

Symptom: the Record Payment modal saves once, then a second submit with the same amount + method + date returns the duplicate error. Cause: expected. The idempotency fingerprint is amount + payment_method + payment_date — a second submit within that fingerprint is treated as the same payment being submitted twice. Fix: if the customer actually paid the same amount twice on the same day, record the second payment under a slightly different date (the next day) or amount (vary by one cent and correct in a future payment). The idempotency guard exists to prevent network-blip double-submissions silently double-counting; the cost is the rare case of a legitimate duplicate needing a small workaround.

Invoice shows status “paid” on the detail page but “partial” on the list

Symptom: the two surfaces disagree on the status badge. Cause: the /invoices list query is cached (revalidate every hour by default) and a payment-recording revalidates a smaller subset than the list page caches. Walking back to /invoices via the browser back button can show the cached payload until the cache TTL elapses. Fix: hard-refresh /invoices (Cmd+Shift+R) — the recordPayment action explicitly revalidates the /invoices path and the cache tag, so the next fresh load picks up the new status. If the discrepancy persists past a refresh, the detail page is the canonical source; the list will correct on the next cache miss.

Cannot record a payment on a voided invoice

Symptom: the Record Payment action returns “Cannot record payment on voided invoice.” Cause: expected. A voided invoice is a closed, non-collectible record — accepting payment against it would muddle the audit trail (was this paid before void? After? Why is a voided invoice carrying a payment?). Fix: if the customer actually paid, issue a fresh invoice with the same line items and record the payment against the new invoice. The original void stays as the audit record of what the customer originally received.

The Avg Days Overdue figure on /invoices?status=overdue looks wrong

Symptom: the Avg Days Overdue cell shows a smaller number than the operator's mental model of how old the overdue invoices are. Cause: the figure is computed across the visible page slice (default 200 invoices per page), not across the full overdue set. For tenants with more than 200 overdue invoices, only the first page's slice is averaged — older overdue invoices on subsequent pages aren't included. Fix: the headline Total Overdue figure uses the unfiltered sum across all matching rows and is the authoritative aggregate. The Avg Days Overdue cell is best used as a quick read on the current page; pagination through older overdue invoices shows the long tail.