Customer Portal & Sharing

The customer portal is the client-facing side of Invotify — everything your customer sees and does without ever creating an account. You generate a secure share link, send it to your client, and they get a clean, branded page where they can read the invoice, download the PDF, and (on Pro) pay online. Meanwhile, you get a quiet record of exactly when and where they opened it.

What the portal does:

• Public invoice view — A token-based link opens the invoice in the browser. No login, no password, no friction for the client.
• PDF download — The client downloads a pixel-perfect A4 PDF of their invoice with one click.
• Online payment (Pro) — A "Pay Now" button takes the client to a secure Stripe checkout for full or partial payment.
• View tracking — Every open is logged: when, from where, view count, and first/last viewed timestamp.
• Email preferences — A one-click unsubscribe and granular control over which emails the client receives.

Two link types:

• Single-invoice link (/invoice/{token}) — Shows one specific invoice with its full detail and a download/pay action.
• Customer portal link (/portal/{token}) — A unified view of the customer's recent invoices, their total outstanding balance, any overdue flag, and credit-note balance, each invoice with its own pay action.

Plans: Public view, PDF download, view tracking, and email-preference management are available on every plan. Online payment from the portal requires a Pro plan with Stripe connected.

Every portal page is branded with your business name and logo, carries a quiet "Powered by Invotify" footer, and is marked noindex so it never shows up in search engines.

Sharing an invoice creates a unique, hard-to-guess share token and turns it into a public link your client can open without logging in. The token is a random UUID — it can't be guessed by incrementing a number — and it maps to exactly one invoice.

How the share token works:

• Generating a link creates a share_token for the invoice and returns a URL of the form https://your-app/invoice/{token}.
• If a token already exists for that invoice, Invotify returns the same one — sharing again won't churn the link or break a URL you already sent.
• The link is the only credential. Anyone with it can view the invoice, so treat it like a private link.
• You can revoke a share link at any time. Revoking clears the token, and the old URL immediately stops working (it returns "not found"). Generate a fresh link to re-share.

Permissions: Generating or revoking a share link requires the "Manage invoices" permission, so only authorized team members can expose an invoice.

What the client receives: When you send an invoice by email, the link (and on Pro, a payment link) can travel with it. You can also copy the share URL and send it through any channel — chat, your own email client, a messaging app.

Sharing the PDF to WhatsApp, Telegram, Slack & co.: The Share dialog on invoices and quotes hands the rendered PDF straight to your device's share sheet (on phones, tablets, and modern desktop browsers). Tap WhatsApp, Telegram, Slack, or Messenger and the PDF is already attached — pick the recipient and send. On browsers without share-sheet file support, Invotify falls back to downloading the PDF and opening the app so you can attach it manually.

When a client opens a share link, they land on a clean, mobile-friendly page that needs no login. There are two experiences depending on the link.

Single invoice page (`/invoice/{token}`): The client sees the full invoice — your business name and logo, the invoice number and status, issue and due dates, billing details, every line item with quantities and totals, and any notes you added. At the bottom are the actions: - Download PDF — Generates and downloads a professional A4 PDF, identical to what you'd send. Generated server-side on demand. - Pay Now — Appears only when a payment link is available and the invoice isn't already paid or cancelled (Pro — see Online Payment below).

Unified portal page (`/portal/{token}`): A dashboard-style overview for the customer across all their invoices with you: - Outstanding balance — The total still owed across every unpaid invoice (not just the one they clicked), with an overdue flag if any are past due. - Credit-note balance — Any issued or applied credit they hold. - Invoice list — Their recent non-draft invoices, paginated, each showing number, dates, status, amount, and a pay action.

Privacy by design: The portal only ever returns a safe subset of data. Internal IDs, the share token itself, and anything unrelated to that customer are stripped from the response. The unified portal scopes strictly to the one customer the token belongs to. Portal responses are sent with no-store caching so nothing sensitive is cached by intermediaries.

On a Pro plan with Stripe connected, the portal turns a view into a payment. The client clicks Pay Now and lands on Stripe's secure hosted checkout — Invotify never touches their card details.

How a portal payment flows: 1. The client opens their invoice or the unified portal and clicks Pay. 2. Invotify creates a Stripe Checkout session for that invoice and redirects the client to it. 3. The client pays on Stripe's hosted page. Their email is pre-filled for a faster checkout. 4. On success they're returned to a confirmation page; if they cancel, they land back gracefully. 5. Stripe confirms the payment and the invoice status updates to Paid automatically.

Full or partial payments: - By default the client pays the full outstanding balance (the amount due, not just the original total — so prior partial payments are accounted for). - If you've enabled partial payments on the invoice, the client can pay a smaller amount. Invotify enforces any minimum-payment amount you set and never lets the client pay more than what's still owed.

Guardrails built in: - Already-paid or cancelled invoices can't be paid again — the Pay button hides and the request is rejected server-side. - The portal payment endpoint is rate-limited to prevent abuse. - The payment amount is validated against the live outstanding balance and Stripe's minimum charge before a session is created.

Important: Online payment requires a Pro plan and a connected Stripe account. Without Stripe connected, the portal still works for viewing and downloading — there's just no Pay button.

Stop wondering whether your client actually opened the invoice. Every time a shared invoice is viewed, Invotify records it — so you know exactly when they saw it, how many times, and from where.

What gets recorded on each view: - Timestamp — When the view happened. - Source — Where the view came from: link (a shared single-invoice link), email, portal, or api. Defaults to link. - Viewer IP — The client's IP address (parsed from the forwarding header), so you can tell repeat opens from the same place apart from new ones. - User-agent — The browser/device string, truncated to a safe length.

Aggregate stats Invotify keeps per invoice: - View count — The running total of opens. - First viewed at — Exactly when the invoice was first opened (stamped once, never overwritten). - Last viewed at — The most recent open. - Unique IPs — How many distinct IP addresses have viewed it.

Where you see it: The invoice's view stats surface on the invoice detail page — a compact badge shows the view count, with first- and last-viewed timestamps on hover, and a live indicator when the invoice was opened recently. The full view log (every individual open with its source, IP, and user-agent) is available through the invoice's views data, scoped to your company.

Abuse protection: The tracking endpoint is rate-limited per IP and per token, so a single client refreshing repeatedly can't inflate your view count, and the endpoint can't be hammered to pad the numbers.

Every email Invotify sends a customer carries an unsubscribe / preferences link, so clients always stay in control of what lands in their inbox. The link works without any login — the unsubscribe token itself proves ownership of the email address.

What clients can control: - Document emails — Invoices, quotes, and other documents sent to them. - Reminder emails — Overdue and upcoming-payment reminders. - Marketing emails — Any promotional or announcement messages.

Each category is an independent on/off toggle. A client who only wants invoices but not reminders can have exactly that — it's not all-or-nothing.

One-click unsubscribe: The preferences page is the same surface as the unsubscribe link in any email. Clients can flip a single category off, or opt out of everything, in one place. Changes save immediately and apply to future sends.

How it stays secure: - The preferences endpoint requires a valid token (rejected if too short or missing), and that token alone authorizes reading and updating the preferences — no account needed. - Only the known, allowed preference keys are accepted, and only boolean values, so the endpoint can't be coerced into changing anything else. - Reads and writes are rate-limited per IP.

Honoring these preferences keeps your sending reputation healthy and keeps you on the right side of anti-spam rules — clients who chose to opt out simply stop receiving that category.