> ## 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.

# Set Up the Client Portal

> Brand the portal, add a custom domain, configure session security, and walk through what your clients see

The client portal is the public face of your billing — clients click an email link and land on your branded portal to view invoices, pay them, see contracts, and manage payment methods. This guide walks through the setup that makes that experience feel like an extension of your brand instead of a generic billing page.

<Info>
  The portal is enabled by default for every Commerce account. This guide focuses on customization (branding, domain) and per-account security settings. If you just sent your first invoice and the link works, the portal is already running.
</Info>

## What you'll do

<Steps>
  <Step title="Brand the portal">
    Logo, colors, footer text.
  </Step>

  <Step title="Set up a custom domain (optional)">
    Map `billing.yourdomain.com` to the portal.
  </Step>

  <Step title="Configure session security">
    Session length, IP logging, multiple billing contacts.
  </Step>

  <Step title="Test the client experience">
    Log in as a client and walk through paying an invoice.
  </Step>
</Steps>

## Step 1: Brand the portal

<Steps>
  <Step title="Open Commerce settings">
    Navigate to `/dashboard/commerce/settings/`.
  </Step>

  <Step title="Upload your logo">
    Recommended: PNG with transparent background, at least 400px wide. Shows on the portal header and on PDF invoices/estimates.
  </Step>

  <Step title="Set primary and accent colors">
    Pick from the color picker or paste hex codes. The portal's buttons, links, and headers use these colors.
  </Step>

  <Step title="Add footer text">
    Your business address, support email, and any disclaimers ("Charges appear as 'Acme LLC' on your statement"). Shows on every portal page and on invoice PDFs.
  </Step>

  <Step title="Preview">
    Click Preview to see the rendered portal with your branding applied.
  </Step>
</Steps>

<Tip>
  Test the portal in light mode and dark mode (most clients have one preference). The portal auto-detects the client's system theme. Use colors that read well on both backgrounds.
</Tip>

## Step 2: Set up a custom domain (optional)

By default, portal URLs look like `https://your-account.hiveku.com/portal/...`. To use your own domain:

<Steps>
  <Step title="Pick a subdomain">
    Most businesses use `billing.yourdomain.com` or `portal.yourdomain.com`. Pick one and stick with it.
  </Step>

  <Step title="Add the domain in Commerce settings">
    Click **Add Custom Domain** and enter the subdomain.
  </Step>

  <Step title="Add the DNS record">
    Hiveku shows you a CNAME record. Add it to your DNS provider:

    ```
    Type:  CNAME
    Name:  billing
    Value: portals.hiveku.com
    TTL:   3600
    ```

    Adjust the Name based on your subdomain choice.
  </Step>

  <Step title="Wait for DNS propagation">
    Typically under 15 minutes; up to 24 hours worst case. Hiveku polls and updates the status to "Verified" once the CNAME resolves.
  </Step>

  <Step title="SSL certificate auto-issues">
    Hiveku provisions a Let's Encrypt cert automatically. Until it's issued (usually within an hour of DNS verification), the domain shows a security warning — wait it out.
  </Step>

  <Step title="Test the URL">
    Visit `https://billing.yourdomain.com/portal/test`. You should see your branded portal's "session not found" page (which is expected — there's no live session, but the domain works).
  </Step>
</Steps>

<Warning>
  Don't switch domains mid-flight. Existing magic-link emails point at the old URL. After changing domains, send fresh links to any clients with active sessions. Old links break.
</Warning>

## Step 3: Configure session security

<Steps>
  <Step title="Session duration">
    Default is 7 days. For higher-security accounts, drop to 24 hours. Clients then need a fresh magic link if their session expires before they finish what they were doing.
  </Step>

  <Step title="IP logging">
    On by default. Each session logs the IP and user-agent used to authenticate. Useful for audit and abuse detection.
  </Step>

  <Step title="Multiple billing contacts">
    Enable if your enterprise clients have multiple people who need portal access (AP team, project lead, exec sponsor). Each contact gets their own magic link and own session, scoped to the same company's data.
  </Step>

  <Step title="Self-serve subscription changes">
    Off by default. Toggle on if you want clients to upgrade/downgrade or cancel from the portal without involving your team. Most B2B service businesses keep this off.
  </Step>
</Steps>

## Step 4: Test as a client

<Steps>
  <Step title="Create a test contact">
    Add a CRM contact with your own email (or a personal one). Mark them as a Commerce client.
  </Step>

  <Step title="Send them a test invoice">
    Use the [Send Your First Invoice](/how-tos/send-first-invoice) flow with the test contact and a small test amount.
  </Step>

  <Step title="Open the invoice email">
    Click through to the portal.
  </Step>

  <Step title="Walk through paying">
    Use Stripe's test card `4242 4242 4242 4242`. Confirm the success page renders correctly with your branding.
  </Step>

  <Step title="Save the payment method">
    Check "Save this card for future payments." Confirm it shows up under the contact's saved methods in CRM.
  </Step>

  <Step title="Visit the portal again">
    Use the portal URL the email links to. You should land in a logged-in session showing the paid invoice and saved card.
  </Step>
</Steps>

## What clients see

The portal's main pages:

<Tabs>
  <Tab title="Outstanding invoices">
    All unpaid invoices, with totals and Pay Now buttons. Hidden if there are no outstanding invoices.
  </Tab>

  <Tab title="Payment history">
    Past paid invoices with downloadable PDFs.
  </Tab>

  <Tab title="Documents">
    Contracts they're a signer on (pending, executed, voided).
  </Tab>

  <Tab title="Subscriptions">
    Active recurring services, next billing date, plan-change options if you've enabled self-serve.
  </Tab>

  <Tab title="Statements">
    Downloadable account statements for any date range, in PDF or CSV.
  </Tab>

  <Tab title="Payment methods">
    Saved cards/ACH on file, with edit/remove controls.
  </Tab>
</Tabs>

## Magic-link authentication

The portal uses magic links rather than passwords:

* Every invoice/estimate/contract email contains a unique link
* Clicking the link creates a session tied to the client's email
* Sessions last 7 days (configurable)
* Single-use: once consumed, that link can't create a new session
* For longer-lived access, the client requests a fresh login email from the portal footer

This is the same pattern as Stripe's customer portal, QuickBooks, and FreshBooks. Clients prefer it because they don't have to remember another password.

## Multiple billing contacts

For enterprise clients with multiple people involved in billing:

<Steps>
  <Step title="Open the company record">
    Navigate to the company in CRM.
  </Step>

  <Step title="Add additional contacts">
    Each as a separate CRM contact with their own email.
  </Step>

  <Step title="Mark them as billing contacts">
    On each contact, set the "Billing Contact" flag. Set one as primary.
  </Step>

  <Step title="Send portal links to each">
    From the company record, click **Send Portal Links** to email a magic link to every billing contact.
  </Step>
</Steps>

Each contact gets their own session, scoped to the same company. The audit log tracks which contact viewed what.

## Disabling the portal for a client

For strict-security industries that won't allow portal access:

<Steps>
  <Step title="Open the contact or company">
    In CRM.
  </Step>

  <Step title="Set 'Disable Portal'">
    On the billing settings tab.
  </Step>

  <Step title="Sends switch to PDF-only">
    Future invoices/estimates send as PDF attachments without portal links. Manual payment instructions ship in the email body.
  </Step>
</Steps>

## Verify it worked

After setup:

* Portal URL loads with your logo and colors
* A test invoice email links to the portal correctly
* A test payment processes successfully and saves the method
* The session expires per your configured duration
* Multiple billing contacts (if enabled) get separate sessions

## Troubleshooting

<AccordionGroup>
  <Accordion title="Custom domain shows a security warning">
    DNS isn't fully propagated, or the SSL certificate hasn't issued yet. Wait up to 24 hours. Verify the CNAME is correct using `dig billing.yourdomain.com` or an online DNS checker.
  </Accordion>

  <Accordion title="Logo looks tiny on the portal">
    The portal renders at a fixed pixel height. Re-upload at higher resolution (400px+ wide) and let the portal scale down. Tiny source images don't scale up well.
  </Accordion>

  <Accordion title="Colors look wrong on dark mode">
    The portal auto-detects system theme. Test both modes — colors that read fine on light backgrounds can vanish on dark. Pick high-contrast accents that work on both.
  </Accordion>

  <Accordion title="Client says the link doesn't work">
    Magic links are single-use. If they clicked once and re-click from a different device, the second click fails. Send a fresh link from the contact's actions menu.
  </Accordion>

  <Accordion title="Multiple billing contacts but only one gets emails">
    Check that all billing contacts have the "Billing Contact" flag set. Email routing only sends to flagged contacts. The primary billing contact gets all emails by default; additional contacts need the flag explicitly.
  </Accordion>

  <Accordion title="Self-serve cancellation is enabled but clients can't cancel">
    Self-serve cancellation requires the subscription's "Allow self-serve cancel" flag. The account-level toggle is the default, but you can override per-subscription. Check the subscription's settings.
  </Accordion>
</AccordionGroup>

## What's next?

<CardGroup cols={2}>
  <Card title="Client Portal Reference" icon="book" href="/commerce/client-portal">
    Full reference for sessions, security, and features.
  </Card>

  <Card title="Send Your First Invoice" icon="rocket" href="/how-tos/send-first-invoice">
    See the portal in action end-to-end.
  </Card>

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

  <Card title="Custom Domain" icon="globe" href="/how-tos/custom-domain">
    More on Hiveku's custom-domain setup.
  </Card>
</CardGroup>