> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Client Portal

> Branded public-facing surface where clients view invoices, pay them, see contract status, and download statements

The Client Portal is the public-facing side of Commerce — a branded web surface where clients view their invoices, pay outstanding balances, see contract status, and download statements without ever needing to log in to your dashboard. Sessions are managed via magic links (no passwords, no account creation), making it frictionless for clients while still secure. Session data lives in `crm_client_portal_sessions`.

## What clients see

When a client clicks the link in an invoice email, they land in a portal session scoped to their record. They see:

* **Outstanding invoices** — All unpaid invoices, with payment buttons
* **Payment history** — Past paid invoices with downloadable PDFs
* **Contracts** — Status of any contracts they're a signer on (pending, executed, voided)
* **Subscriptions** — Active recurring services with next billing dates
* **Statements** — Downloadable account statements (PDF) for any date range
* **Saved payment methods** — Cards or ACH on file, with edit/remove controls

What they don't see: any other client's data, your internal notes, your team's messages, or any non-billing surfaces.

## How sessions work

<Steps>
  <Step title="Magic link in email">
    Every invoice, estimate, and contract email contains a unique link to the portal scoped to that document and that client.
  </Step>

  <Step title="Session creation on click">
    Clicking the link creates a `crm_client_portal_sessions` record with a time-limited token. The session lasts 7 days by default.
  </Step>

  <Step title="No password, no account">
    The client doesn't create an account. The magic link itself proves identity (sent to their verified email).
  </Step>

  <Step title="Session expiry">
    After 7 days, the session expires. Clicking a fresh link creates a new session. For longer-lived access, the client can request a portal-only login email any time from the portal footer.
  </Step>
</Steps>

<Info>
  Magic-link authentication is the standard for billing portals (Stripe Customer Portal, QuickBooks invoice portals, FreshBooks). Clients prefer it because they don't have to remember another password, and it's secure because the link is single-use and tied to their email.
</Info>

## Branding

The portal inherits your account's brand settings:

<Steps>
  <Step title="Logo">
    Upload a logo from account settings. Shown on the portal header and on PDF invoices/estimates.
  </Step>

  <Step title="Colors">
    Set primary and accent colors. The portal's buttons, links, and headers use them.
  </Step>

  <Step title="Footer text">
    Custom footer with your business address, support email, and any disclaimers.
  </Step>

  <Step title="Custom domain (optional)">
    Map `billing.yourdomain.com` to the portal so the URL reflects your brand instead of `hiveku.com`. See [Set Up the Client Portal](/how-tos/setup-client-portal) for the DNS setup.
  </Step>
</Steps>

## Paying an invoice through the portal

For the client, paying an invoice looks like:

1. Click the link in the invoice email
2. Land on the portal showing their outstanding invoice
3. Click **Pay Now**
4. Pick a saved payment method or enter a new card
5. Submit — payment processes through Stripe or Authorize.Net
6. See the invoice flip to `paid` immediately, with a receipt emailed to them

If their first attempt fails (insufficient funds, incorrect CVC), the portal shows a friendly error and lets them retry without restarting from the email link.

## Saved payment methods

Clients can save a card or ACH (where supported) for future use. Saved methods are stored at the processor (Stripe Customer or Authorize.Net Customer Profile) — Hiveku stores only the reference, not the card data. This keeps your PCI scope minimal.

Clients can:

* Add a new payment method
* Set a default
* Remove a method
* See the masked last-4 digits of each saved card

You can also set saved methods on the client's behalf if they email you their card info (don't do this — recommend the portal instead).

## Subscriptions in the portal

For clients with active subscriptions, the portal shows:

* The subscription's plan and price
* Next billing date
* Upgrade/downgrade options (if you've enabled self-serve plan changes)
* Cancel option (if you've enabled self-serve cancellation)

Self-serve changes are off by default — most B2B service businesses prefer plan changes to go through their account manager. Toggle on per-account if your business is more self-serve.

## Contracts in the portal

If a client is a signer on a sent contract, the portal shows it under **Documents**. They can:

* Resume signing if they started but didn't finish
* Download the executed PDF once all signers complete
* See the audit trail for any executed contract

This is useful even for clients who already signed — they can pull the signed PDF anytime without emailing you.

## Statements

The portal supports downloadable statements:

* **Date range** — Custom from/to dates
* **Format** — PDF or CSV
* **Contents** — Invoices issued, payments received, current balance

Useful for clients' year-end accounting close or expense reporting.

## Security

* **Magic links are single-use per send.** A used link can't be re-used to create a new session — the client requests a fresh one if needed.
* **Sessions are time-bounded.** 7-day default; configurable per account.
* **TLS-only.** All portal traffic over HTTPS.
* **PCI scope is the processor's.** Card data never touches Hiveku servers — it's tokenized client-side and stored at Stripe/Authorize.Net.
* **Email verification.** Magic links go to the email on file; clients can't redirect them.
* **IP and user-agent logging.** Each session logs the IP and browser used, viewable in the client's audit log.

<Warning>
  Don't forward magic-link emails to colleagues — the link is tied to the original recipient. If multiple people need access, add them as additional billing contacts on the client record so each gets their own link.
</Warning>

## Multiple billing contacts

A client (especially an enterprise client) might need multiple people to access the portal — accounts payable, the project lead, the executive sponsor. Add multiple billing contacts on the company record. Each gets their own magic link and their own session, scoped to the same company's data.

The audit log shows which contact viewed which document, useful for tracking who pulled a statement or paid an invoice.

## Disabling the portal for a client

If a client requests no portal access (rare, but happens with strict-security industries), you can disable portal links for their account. Invoices then send via PDF attachment only, with manual payment instructions. Toggle in the client's settings.

## API patterns

The portal isn't typically API-driven (it's a hosted UI), but related endpoints include:

* `POST /api/crm/client-portal-sessions` — create a magic-link session for a contact
* `GET /api/crm/client-portal-sessions/:id` — session details and audit
* `POST /api/crm/contacts/:id/portal-link` — generate a fresh magic link for a contact

## Troubleshooting

<AccordionGroup>
  <Accordion title="Client says the portal link doesn't work">
    Check the session's status — single-use links expire on first click. If they clicked it, then re-clicked from a different device, the second click fails. Send a fresh link from the invoice or contact's actions menu.
  </Accordion>

  <Accordion title="Client can't see the new invoice">
    The portal scopes by client record. Make sure the invoice is sent (not draft) and is associated with the same contact/company as the session. If you sent the invoice to a different contact at the same company, that contact has its own session.
  </Accordion>

  <Accordion title="Custom domain shows a security warning">
    DNS isn't fully propagated, or the SSL certificate hasn't issued yet. Setup takes up to 24 hours after the DNS records are correct. See [Set Up the Client Portal](/how-tos/setup-client-portal) for the DNS records and timing.
  </Accordion>

  <Accordion title="Payment method updates aren't sticking">
    Check the processor connection (Stripe or Authorize.Net) — if it's disconnected or has expired credentials, the portal can save the method to Hiveku's record but the processor won't store the actual token. Re-authorize the connection in [Payments](/commerce/payments).
  </Accordion>

  <Accordion title="Client wants to delete their account from the portal">
    There's no self-serve delete — billing records are retained for accounting reasons. If the relationship is over, mark them inactive in CRM. For GDPR / privacy-law deletion requests, see your account's privacy settings.
  </Accordion>
</AccordionGroup>

## What's next?

<CardGroup cols={2}>
  <Card title="Set Up the Client Portal" icon="rocket" href="/how-tos/setup-client-portal">
    Branding, custom domain, and security walkthrough.
  </Card>

  <Card title="Invoices" icon="file-invoice-dollar" href="/commerce/invoices">
    What clients see and pay through the portal.
  </Card>

  <Card title="Payments" icon="credit-card" href="/commerce/payments">
    Connect Stripe or Authorize.Net to enable portal payments.
  </Card>

  <Card title="Contracts" icon="signature" href="/commerce/contracts">
    Documents that show up in the portal's Documents section.
  </Card>
</CardGroup>