# Introduction (/docs)





## Welcome to PineBill [#welcome-to-pinebill]

**Run your entire business from one place.** PineBill is the all-in-one business management tool for freelancers and small teams — manage clients, projects, and invoices in one place, and automate the busywork. Create professional invoices and estimates, track expenses and billable hours, put repeat billing and payment chasing on autopilot, and let the AI assistant handle routine tasks so you can focus on the work.

## What You Can Do with PineBill [#what-you-can-do-with-pinebill]

### Invoicing & Billing [#invoicing--billing]

* **Professional Invoice Templates**: Four professional designs — Standard, Bold Professional, Mono and Startup Modern — with your company branding, smart invoice numbering and custom fields
* **Smart Invoice Generation**: Create invoices quickly with product-based and hourly billing modes, and automatic calculations for taxes, discounts, and shipping
* **Estimates & Quotes**: Send professional estimates, let clients accept or decline right from a share link, and convert approved quotes into invoices with one click
* **Recurring Invoices**: Automate repetitive billing with flexible schedules — weekly through yearly — and auto-send each generated invoice by email
* **Payment Reminders**: Turn them on once and PineBill chases the invoice for you — before, on and after the due date — then stops the moment your client pays
* **Secure Invoice Sharing**: Send invoices by email with the PDF attached, or share password-protected links with expiration dates and view limits
* **Payment Tracking**: Monitor invoice statuses (Draft, Sent, Paid, Overdue, Cancelled) and track payment history
* **Global Invoicing**: Invoice in 12 languages with locale-aware currency formatting, full right-to-left layout for Arabic, and daily-refreshed exchange rates that every invoice records at issue time

### Running the Business [#running-the-business]

* **AI Assistant**: Ask by chat or voice — create invoices, find customer information, summarize outstanding balances, and handle routine tasks. Every change waits on an approval card you review first
* **Expense Tracking**: Log every cost with categories and receipts, or scan a receipt and let AI fill in the expense — then bill the billable ones back as invoice line items
* **Projects & Time Tracking**: Group tasks, invoices, estimates and expenses per project, move work across a Kanban board, and turn server-tracked hours into invoice line items at each task's rate
* **Calendar**: Your events, task deadlines, invoice due dates, project deadlines and expense dates on one colour-coded grid
* **Customer Management**: Build a comprehensive customer database with detailed profiles, contact information, addresses, and timezone support
* **Product Catalog**: Organize your products and services with categories, SKUs, pricing, and photos for quick invoice creation
* **Team Collaboration**: Invite team members with role-based permissions (Admin, Member, Guest) and assign invoices to employees

### Insights & Infrastructure [#insights--infrastructure]

* **Advanced Analytics**: Track sales trends, customer lifetime value, and product performance with real-time insights and visual reports
* **File Vault**: Securely store and share files with your organization using S3-compatible cloud storage with signed URLs
* **Security & Compliance**: AES-256 encryption, API key security, audit logging, and role-based access
* **API Integration**: Integrate PineBill with your applications using our comprehensive REST API

## Getting Started [#getting-started]

New to PineBill? Follow our quick start guide to create your first invoice in under 15 minutes:

<Cards>
  <Card title="Create Your Account" description="Sign up and set up your organization profile with company branding" href="/docs/getting-started/create-account" />

  <Card title="Create Your First Invoice" description="Complete tutorial to generate and share your first professional invoice" href="/docs/getting-started/first-invoice" />
</Cards>

## Documentation Sections [#documentation-sections]

Explore our comprehensive documentation to make the most of PineBill:

### Core Features [#core-features]

<Cards>
  <Card title="Getting Started" description="Quick start guides, account setup, and interface overview for new users" href="/docs/getting-started" icon="<RocketIcon className=&#x22;text-primary&#x22; />" />

  <Card title="Invoices" description="Master invoice creation, templates, statuses, sharing, and settings" href="/docs/invoices" icon="<FileTextIcon className=&#x22;text-primary&#x22; />" />

  <Card title="Estimates" description="Send quotes, collect client approval, and convert accepted estimates to invoices" href="/docs/estimates" icon="<FileCheckIcon className=&#x22;text-primary&#x22; />" />

  <Card title="Recurring Invoices" description="Put repeat billing on autopilot with flexible schedules and auto-send" href="/docs/recurring-invoices" icon="<RepeatIcon className=&#x22;text-primary&#x22; />" />

  <Card title="Customers" description="Build and manage your customer database effectively" href="/docs/customers" icon="<UsersIcon className=&#x22;text-primary&#x22; />" />

  <Card title="Products" description="Organize your product catalog with categories and pricing" href="/docs/products" icon="<PackageIcon className=&#x22;text-primary&#x22; />" />
</Cards>

### Work Management [#work-management]

<Cards>
  <Card title="Projects" description="One workspace per piece of work — tasks, documents and costs together" href="/docs/projects" icon="<FolderKanbanIcon className=&#x22;text-primary&#x22; />" />

  <Card title="Tasks & Time Tracking" description="Kanban boards, built-in timers, and billing tracked hours to invoices" href="/docs/tasks" icon="<TimerIcon className=&#x22;text-primary&#x22; />" />

  <Card title="Expenses" description="Track costs, scan receipts with AI, and bill expenses back to clients" href="/docs/expenses" icon="<ReceiptIcon className=&#x22;text-primary&#x22; />" />

  <Card title="Calendar" description="Events, deadlines and due dates from across PineBill on one grid" href="/docs/calendar" icon="<CalendarIcon className=&#x22;text-primary&#x22; />" />

  <Card title="AI Assistant" description="Chat and voice assistant that acts on your records — with your approval" href="/docs/ai-assistant" icon="<BotIcon className=&#x22;text-primary&#x22; />" />

  <Card title="Employees" description="Manage team members, assignments, and access" href="/docs/employees" icon="<UserCogIcon className=&#x22;text-primary&#x22; />" />
</Cards>

### Advanced Features [#advanced-features]

<Cards>
  <Card title="Payments" description="Payment methods, multi-currency support, and payment tracking" href="/docs/payments" icon="<CreditCardIcon className=&#x22;text-primary&#x22; />" />

  <Card title="Organization" description="Company settings, team management, roles, and permissions" href="/docs/organization" icon="<BuildingIcon className=&#x22;text-primary&#x22; />" />

  <Card title="Analytics" description="Business insights, revenue tracking, and performance metrics" href="/docs/analytics" icon="<BarChartIcon className=&#x22;text-primary&#x22; />" />

  <Card title="Notifications" description="Stay on top of invoice views, approvals, and team activity" href="/docs/notifications" icon="<BellIcon className=&#x22;text-primary&#x22; />" />

  <Card title="File Vault" description="Secure file storage, organization, and sharing capabilities" href="/docs/vault" icon="<FolderIcon className=&#x22;text-primary&#x22; />" />
</Cards>

### Integration & Support [#integration--support]

<Cards>
  <Card title="API" description="REST API integration, authentication, and endpoint reference" href="/docs/api" icon="<SettingsIcon className=&#x22;text-primary&#x22; />" />

  <Card title="Subscription" description="Plans, pricing, usage limits, and billing management" href="/docs/subscription" icon="<CreditCardIcon className=&#x22;text-primary&#x22; />" />

  <Card title="Troubleshooting" description="Common issues, solutions, and how to get support" href="/docs/troubleshooting" icon="<HelpCircleIcon className=&#x22;text-primary&#x22; />" />
</Cards>

## Quick Links [#quick-links]

* [API Documentation](https://api.pinebill.app/docs/) - Complete REST API reference.
* [Dashboard](/dashboard) - Go to your PineBill dashboard.
* [Support](/contact-us) - Contact with our support team.

## Need Help? [#need-help]

If you can't find what you're looking for in our documentation:

* Check our [Troubleshooting Guide](/docs/troubleshooting) for common issues

Let's get started with PineBill and run your entire business from one place!


# General (/docs/ai-assistant)







## Quick Start [#quick-start]

PineBill Assistant helps you work inside your PineBill dashboard with text chat, voice input, file attachments, and approved actions.

Open your dashboard and click **Ask AI**.

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-05-19-2026_01_23_PM.png" alt="PineBill Assistant chat panel" maxHeight="500px" className="w-full p-2" />

You can use it to:

* Find and summarize business records
* Create invoices, estimates, customers, products, projects, tasks, expenses, payment methods, and employees
* Update or delete records after approval
* Send invoice and estimate emails after approval
* Review revenue, invoice, customer, product, expense, employee, and dashboard analytics
* Use voice input when typing is slower

<Callout type="info">
  PineBill Assistant is focused on PineBill work. It is not a general-purpose chatbot.
</Callout>

***

## Text, Voice, and Files [#text-voice-and-files]

| Input          | What it does                                                                  |
| -------------- | ----------------------------------------------------------------------------- |
| **Text chat**  | Type requests, ask follow-up questions, and review results in the chat panel  |
| **Voice**      | Speak instead of typing. Use the microphone button to start or stop dictation |
| **Hands-free** | Keeps voice mode ready after assistant replies                                |
| **Auto-send**  | Sends your dictated message when dictation ends                               |
| **Files**      | Attach images, PDFs, TXT, CSV, or Markdown files up to 3 MB                   |

Use voice for quick work like creating tasks, finding invoices, checking totals, or updating records while you are already focused on another workflow.

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-05-19-2026_01_28_PM.png" alt="Voice input controls in PineBill Assistant" maxHeight="360px" className="mb-4 w-full p-2" />

<Cards>
  <Card title="Voice Mode" description="Use dictation, auto-send, and hands-free mode for faster dashboard work" href="/docs/ai-assistant/voice-mode" />
</Cards>

***

## Approval Before Changes [#approval-before-changes]

For actions that create, update, delete, or send something, PineBill shows an approval card before the action is completed.

Examples:

* Creating an invoice
* Updating a customer
* Deleting a task
* Sending an invoice email
* Creating a payment method

Review the card, then approve or cancel the action.

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-05-19-2026_01_29_PM.png" alt="Assistant approval card before completing an action" maxHeight="360px" className="w-full p-2" />

***

## Available Tools [#available-tools]

### Invoices [#invoices]

* List, search, and fetch invoice details
* Create invoices from customers, products, temporary line items, dates, taxes, discounts, and payment methods
* Update invoice content or status
* Send invoice emails
* Delete invoices after approval

### Estimates [#estimates]

* List, fetch, create, update, and delete estimates
* Send estimate emails
* Prepare estimates that can later become invoices

### Customers [#customers]

* Add new customers
* Find customers by name or details
* Update customer records
* Delete customers when allowed

### Products and Services [#products-and-services]

* List products and prices
* Add catalog items
* Update product details
* Delete products when allowed

### Payment Methods [#payment-methods]

* List saved payment methods
* Add bank transfer, PayPal, crypto, or custom payment methods
* Update payment method details
* Set defaults or remove methods when allowed

### Projects and Tasks [#projects-and-tasks]

* Create and manage projects
* List tasks and update task status
* Create tasks with due dates, hourly rates, notes, projects, or assignees
* Delete projects or tasks after approval

### Expenses [#expenses]

* Record expenses
* Search and review expenses
* Update expense details
* Delete expenses after approval

### Employees [#employees]

* List employees
* Add employee records
* View employee details
* Update or deactivate employees

### Analytics [#analytics]

| Plan              | Analytics the assistant can help with                                  |
| ----------------- | ---------------------------------------------------------------------- |
| **All plans**     | Dashboard overview, revenue trends, invoice analytics, customer growth |
| **Pro and above** | Invoice aging, expense analytics, product analytics                    |
| **Enterprise**    | Advanced metrics, employee performance, customer lifetime value        |

***

## AI Credits [#ai-credits]

AI Assistant uses credits for chat and voice.

| Usage             | Credit cost |
| ----------------- | ----------- |
| **Text message**  | 2 credits   |
| **Voice session** | 4 credits   |

Credits are tracked at the organization level. You can view your balance, usage history, and active top-ups from &#x2A;*[Settings](/dashboard/setup)*&#x2A; -> &#x2A;*[Subscription](/dashboard/subscription)** -> **AI Credits**.

### Monthly Plan Credits [#monthly-plan-credits]

| Plan           | Monthly AI credits |
| -------------- | ------------------ |
| **Trial**      | 70 credits         |
| **Solo**       | 500 credits        |
| **Pro**        | 3,000 credits      |
| **Enterprise** | 10,000 credits     |

Monthly credits reset each billing period.

### Top-Up Packs [#top-up-packs]

| Pack              | Price |
| ----------------- | ----- |
| **500 credits**   | $5    |
| **2,000 credits** | $10   |
| **5,000 credits** | $20   |

Top-up credits expire 12 months after purchase. Organization owners can buy more credits from the subscription page.

<Callout type="tip">
  If your balance is low, PineBill shows a warning in the chat panel. If credits run out, you can
  top up or upgrade your plan.
</Callout>

***

## Example Prompts [#example-prompts]

### Daily Work [#daily-work]

```text
Show me my recent invoices and summarize which ones are paid, unpaid, overdue, or draft.
```

```text
Create a task for redesign work due next Friday with an hourly rate of $80.
```

```text
List my current projects and group them by status.
```

```text
Show my recent expenses and total them by category.
```

### Invoices and Estimates [#invoices-and-estimates]

```text
Help me create an invoice for Acme Corp with 5 hours of consulting at $120 per hour.
```

```text
Send invoice INV-1024 to the customer's email with a short payment reminder.
```

```text
Create an estimate for website maintenance, 10 hours at $90 per hour.
```

```text
Mark invoice INV-1030 as paid today.
```

### Customers, Products, and Payments [#customers-products-and-payments]

```text
Add a customer named Northwind Studio with billing email billing@northwind.example.
```

```text
List my products and show any items that look underpriced.
```

```text
Create a PayPal payment method named Main PayPal.
```

### Analytics [#analytics-1]

```text
Give me a dashboard overview for this month.
```

```text
Show revenue trends for the last 90 days.
```

```text
Which customers have the highest lifetime value?
```

***

## How It Improves Productivity [#how-it-improves-productivity]

* **Less clicking**: Ask for a result instead of navigating through several pages.
* **Faster creation**: Create invoices, tasks, customers, products, and expenses from one chat.
* **Safer edits**: Review approval cards before PineBill changes or sends anything.
* **Better follow-up**: Ask natural follow-up questions after a list or analytics result.
* **Hands-free work**: Use voice when you are reviewing records, on a call, or moving between tasks.
* **Quick insight**: Ask for summaries instead of manually checking invoices, revenue, expenses, or customers.

***

## Common Questions [#common-questions]

<Accordions type="single">
  <Accordion title="Can the assistant create records for me?" id="create-records">
    Yes. It can create invoices, estimates, customers, products, payment methods, projects, tasks, expenses, and employees. PineBill asks you to approve important actions before completing them.
  </Accordion>

  <Accordion title="Can I use voice instead of typing?" id="voice-input">
    Yes. Click the microphone button to dictate. You can also use auto-send after dictation or
    hands-free mode from chat settings.
  </Accordion>

  <Accordion title="What happens if I run out of credits?" id="out-of-credits">
    The assistant stops processing new requests until you top up or upgrade your plan. You can buy
    credits from the subscription page.
  </Accordion>

  <Accordion title="Who can buy top-up credits?" id="top-up-owner">
    Organization owners can buy top-up credits.
  </Accordion>

  <Accordion title="Can I attach files?" id="attachments">
    Yes. You can attach images, PDFs, TXT, CSV, or Markdown files up to 3 MB.
  </Accordion>
</Accordions>


# Voice Mode (/docs/ai-assistant/voice-mode)







## Quick Start [#quick-start]

Voice mode lets you speak to PineBill Assistant instead of typing. It is useful when you want to create records, check totals, update tasks, or ask follow-up questions quickly.

Open &#x2A;*[Dashboard](/dashboard)**, click **Ask AI**, then click the microphone button.

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-05-19-2026_01_28_PM.png" alt="Start voice mode in PineBill Assistant" maxHeight="500px" className="w-full p-2" />

***

## Voice Controls [#voice-controls]

| Control             | What it does                                                                  |
| ------------------- | ----------------------------------------------------------------------------- |
| **Microphone**      | Starts voice input when the message box is empty                              |
| **Stop voice**      | Stops listening and keeps the dictated text in the message box                |
| **Send**            | Sends the dictated message to the assistant                                   |
| **Hands-free mode** | Restarts listening after each assistant reply so you can continue by speaking |
| **Chat settings**   | Lets you turn auto-send after dictation on or off                             |

***

## Dictation Mode [#dictation-mode]

Use normal dictation when you want to speak one message, review it, then send it.

1. Click the microphone button.
2. Speak your request.
3. Click stop, or wait for dictation to finish.
4. Review the text.
5. Send the message.

Good for:

* Creating an invoice with several details
* Asking for a summary
* Checking records before making a change
* Dictating a task or expense note

Example:

```text
Create a task for the website redesign due next Friday and set the hourly rate to $85.
```

***

## Auto-Send After Dictation [#auto-send-after-dictation]

Auto-send sends your message automatically after dictation ends.

Turn it on from **Chat settings** -> **Auto-send after dictation**.

Use auto-send when:

* You usually speak short, clear requests
* You want fewer clicks
* You are using voice repeatedly

Turn it off when:

* You want to review dictated text first
* You are speaking names, prices, invoice numbers, or email addresses
* Your environment is noisy

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-05-19-2026_01_31_PM.png" alt="Voice settings for auto-send after dictation" maxHeight="420px" className="w-full p-2" />

***

## Hands-Free Mode [#hands-free-mode]

Hands-free mode keeps voice input ready after each assistant response. After PineBill Assistant replies, it starts listening again so you can continue the workflow without clicking the microphone each time.

Use hands-free mode for multi-step work:

1. Click the hands-free button in the chat composer.
2. Say your first request.
3. Wait for the assistant response.
4. Speak your follow-up when listening starts again.
5. Turn hands-free off when you are done.

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-05-19-2026_01_32_PM.png" alt="Hands-free mode active in PineBill Assistant" maxHeight="420px" className="w-full p-2" />

<Callout type="info">
  Hands-free mode works best with auto-send enabled. If hands-free is on, PineBill can send dictated
  follow-ups automatically so the conversation keeps moving.
</Callout>

***

## Best Use Cases [#best-use-cases]

### Create Work Quickly [#create-work-quickly]

```text
Add a new task called review client contract due tomorrow.
```

```text
Create an expense for software renewal, $49, category software.
```

### Review Business Status [#review-business-status]

```text
Show my overdue invoices and summarize who owes the most.
```

```text
Give me a dashboard overview for this month.
```

### Continue With Follow-Ups [#continue-with-follow-ups]

```text
Now create a reminder task for the largest overdue invoice.
```

```text
Send that invoice to the customer with a short payment reminder.
```

***

## Tips for Better Voice Results [#tips-for-better-voice-results]

* Speak one request at a time.
* Include names, dates, prices, and quantities when you know them.
* Say invoice numbers clearly, for example: "invoice I N V dash 1024."
* Pause before ending dictation so the last words are captured.
* Review approval cards before PineBill creates, updates, deletes, or sends anything.
* Turn hands-free off before private conversations or background noise.

***

## Common Questions [#common-questions]

<Accordions type="single">
  <Accordion title="Does hands-free mode send every response automatically?" id="hands-free-auto-send">
    Hands-free mode keeps listening after assistant replies. Auto-send controls whether dictated text is sent automatically after dictation ends.
  </Accordion>

  <Accordion title="Can I edit dictated text before sending?" id="edit-dictation">
    Yes. Turn off auto-send if you want to review and edit dictated text before sending.
  </Accordion>

  <Accordion title="When should I avoid hands-free mode?" id="avoid-hands-free">
    Avoid it in noisy rooms, meetings, or any place where private conversation could be picked up by
    the microphone.
  </Accordion>

  <Accordion title="Will PineBill make changes without approval?" id="voice-approval">
    No. Important actions such as creating, updating, deleting, or sending records still show approval cards.
  </Accordion>
</Accordions>


# Analytics (/docs/analytics)





## Quick Start [#quick-start]

Analytics provides insights into your business performance. Access it from &#x2A;*[Dashboard](/dashboard)*&#x2A; → &#x2A;*[Analytics](/dashboard/analytics)**.

<DocImage src="https://storage.pinebill.app/public/docs/image/Analytics-PineBill-12-01-2025_08_56_PM.webp" alt="Analytics dashboard page" maxHeight="500px" className="w-full p-0" />

***

## Date Range Selection [#date-range-selection]

All charts and metrics update based on the selected date range:

| Period         | Description                           |
| -------------- | ------------------------------------- |
| Last 7 days    | Data from the past week               |
| Last 30 days   | Data from the past month              |
| Last 90 days   | Data from the past quarter            |
| Last 12 months | Data from the past year               |
| Year to date   | From January 1st to today             |
| This year      | All data in the current calendar year |

**To change date range:**

1. Click the date range dropdown (top-right)
2. Select a period
3. All charts update automatically

**Refresh button:**

* Click the refresh icon to reload all data
* Useful after creating new invoices or customers

<DocImage src="https://storage.pinebill.app/public/docs/image/Analytics-PineBill-12-01-2025_08_58_PM.png" alt="Date range selection dropdown" maxHeight="300px" className="w-full p-0" />

***

## Basic Metrics [#basic-metrics]

Available on all subscription plans. Four metric cards display at the top:

### Total Invoices [#total-invoices]

* Count of all invoices in the selected period
* Trend percentage vs previous period
* Mini sparkline chart showing invoice creation over time

### Total Sales [#total-sales]

* Revenue from all paid invoices
* Converted to your organization's default currency
* Multi-currency invoices automatically converted using current exchange rates
* Trend percentage vs previous period
* Mini sparkline chart showing revenue over time

### Active Customers [#active-customers]

* Total number of customers
* Shows new customers added in the selected period
* Mini sparkline chart showing customer growth

### Avg Invoice Value [#avg-invoice-value]

* Average revenue per invoice
* Calculated as: Total Sales ÷ Total Invoices
* Displayed in organization currency
* Mini sparkline chart showing average value trend

<DocImage src="https://storage.pinebill.app/public/docs/image/Analytics-PineBill-12-01-2025_09_00_PM.png" alt="Four metric cards showing key statistics" maxHeight="400px" className="w-full p-0" />

**Currency Handling:**

* All amounts display in your organization's default currency
* Invoices in different currencies (EUR, GBP, etc.) are converted automatically
* Uses current exchange rates from the currency store

***

## Advanced Analytics (Pro+ Plans) [#advanced-analytics-pro-plans]

Advanced charts require a **Pro** or **Enterprise** subscription.

### Total Sales Trends [#total-sales-trends]

Line chart showing revenue over time:

* Grouped by day, week, or month depending on date range
* Hover over points to see exact amounts
* All currencies converted to organization currency
* Identifies revenue patterns and trends

<DocImage src="https://storage.pinebill.app/public/docs/image/Analytics-PineBill-12-01-2025_08_59_PM.webp" alt="Revenue line chart over time" maxHeight="400px" className="w-full p-0" />

### Customer Growth [#customer-growth]

Line chart showing customer acquisition:

* Total customers over time
* New customers added each period
* Grouped by time period
* Shows growth rate

### Invoice Volume [#invoice-volume]

Stacked area chart showing invoice creation by status:

* Draft invoices (gray)
* Sent invoices (blue)
* Paid invoices (green)
* Overdue invoices (red)
* Cancelled invoices (orange)
* Hover to see count for each status

<DocImage src="https://storage.pinebill.app/public/docs/image/Analytics-PineBill-12-01-2025_09_02_PM.png" alt="Invoice volume stacked area chart" maxHeight="400px" className="w-full p-0" />

### Invoice Status Distribution [#invoice-status-distribution]

Pie chart showing current invoice breakdown:

* Percentage by status
* Total count for each status
* Click legend items to show/hide statuses
* Helps identify bottlenecks

### Top Products [#top-products]

Horizontal bar chart showing best-selling products:

* Top 10 products by revenue
* Revenue amounts in organization currency
* Helps identify your most profitable products

<DocImage src="https://storage.pinebill.app/public/docs/image/Analytics-PineBill-12-01-2025_09_03_PM.png" alt="Top products bar chart" maxHeight="400px" className="w-full p-0" />

### Product Trends [#product-trends]

Line chart showing sales trends for top products:

* Up to 5 products shown
* Color-coded by product
* Revenue over time
* Hover to see exact amounts
* Identifies seasonal patterns

### Expense Analytics [#expense-analytics]

Expense charts show how business spending changes over time.

You can review:

* Total expense amount for each period
* Expense count for each period
* Spending in your organization's default currency
* Trends grouped by day, week, month, quarter, or year

<DocImage src="/docs/placeholders/expenses/expense-analytics.png" alt="Expense analytics charts" maxHeight="450px" className="w-full p-0" />

### Expense Bar Chart [#expense-bar-chart]

The grouped expense bar chart is useful for comparing spending across larger periods.

Use it to quickly answer:

* Which month had the highest spending?
* Are expenses increasing or decreasing?
* How many expense records were created in each period?
* Do spending spikes match travel, contractors, software renewals, or other categories?

***

## Enterprise Analytics (Enterprise Plan) [#enterprise-analytics-enterprise-plan]

Enterprise-level insights require an **Enterprise** subscription.

### Employee Performance [#employee-performance]

Leaderboard showing top employees by revenue:

* Employee name and performance metrics
* Total revenue generated
* Invoice count
* Conversion rate (paid invoices ÷ total invoices)
* Sorted by total revenue
* All amounts in organization currency

### Employee Performance Trends [#employee-performance-trends]

Line chart showing employee performance over time:

* Tracks up to 5 top employees
* Color-coded by employee
* Switchable metrics using dropdown:
  * **Sales Amount**: Revenue generated
  * **Invoice Count**: Number of invoices created
  * **Conversion Rate**: Percentage of paid invoices

**To change metric:**

1. Click the metric dropdown (top-right of chart)
2. Select Sales Amount, Invoice Count, or Conversion Rate
3. Chart updates immediately

<DocImage src="https://storage.pinebill.app/public/docs/image/Analytics-PineBill-12-01-2025_09_04_PM.png" alt="Employee performance trends over time" maxHeight="400px" className="w-full p-0" />

### Customer Lifetime Value (LTV) [#customer-lifetime-value-ltv]

Three metric cards showing customer value:

**Total Customers:**

* Count of all customers tracked

**Avg Customer LTV:**

* Average lifetime value per customer
* Calculated as: Total revenue from all customers ÷ Total customers
* Estimated value in organization currency

**Total LTV:**

* Cumulative lifetime value across all customers
* Sum of all customer revenue
* Organization currency

***

## Understanding the Data [#understanding-the-data]

### Multi-Currency Support [#multi-currency-support]

Analytics automatically handles multiple currencies:

* All invoices converted to organization default currency
* All expenses converted to organization default currency
* Uses current exchange rates from currency store
* Ensures accurate totals across different currencies
* Example: USD invoices + EUR invoices = total in USD (or your default currency)

### Date Grouping [#date-grouping]

Charts automatically group data based on date range:

* **7-30 days**: Grouped by day
* **90 days**: Grouped by week
* **12 months+**: Grouped by month

### Empty States [#empty-states]

If no data exists for the selected period:

* Charts show "No data available" message
* Metric cards show zero values
* Create invoices, customers, products, or expenses to start seeing analytics

### Subscription Limits [#subscription-limits]

**Basic Plan:**

* 4 metric cards only
* No charts

**Pro Plan:**

* All basic metrics
* Advanced revenue, invoice, customer, product, and expense charts
* Product analytics

**Enterprise Plan:**

* All Pro features
* Employee performance tracking
* Customer lifetime value
* Employee trend analysis

***

## Performance Notes [#performance-notes]

* Charts load dynamically to improve page speed
* Large date ranges (12 months+) may take longer to load
* Refresh button reloads all data
* Data updates in real-time as you create invoices

***

## Related Topics [#related-topics]

* [Creating Invoices](/docs/invoices/creating-invoices) - Generate data for analytics
* [Expenses](/docs/expenses) - Track costs for expense analytics
* [Subscription Plans](/docs/subscription) - Upgrade for advanced analytics
* [Dashboard](/docs/getting-started) - Quick overview metrics


# API Audit Logs (/docs/api/api-audit)







## Quick Start [#quick-start]

API audit logs provide a comprehensive record of all API requests made to your organization. Monitor usage, debug issues, and detect security threats from &#x2A;*[Settings](/dashboard/setup)** → **API Access and Activity*&#x2A; → &#x2A;*[API Audit Logs](/dashboard/organization/audit/api-logs)**.

<Callout type="info">
  **Permissions**: Organization admins and members can view API logs. Guests cannot access audit
  logs.
</Callout>

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-04-15-2026_04_30_PM.png" alt="Invoice Generator Overview" maxHeight="400px" className="w-full p-0" />

<DocImage src="https://storage.pinebill.app/public/docs/image/My-Organization-12-02-2025_09_10_PM.webp" alt="Invoice Generator Overview" maxHeight="400px" className="w-full p-0" />

***

## What Are API Audit Logs? [#what-are-api-audit-logs]

API audit logs record every API request made to your organization, including:

* **Request Details**: Method, endpoint, timestamp
* **Authentication**: Which API key was used
* **Response Status**: Success or error codes
* **Network Info**: IP address and user agent
* **Performance**: Request timing and processing

**Use cases:**

* Monitor API usage patterns
* Debug integration issues
* Detect suspicious activity
* Track API key performance
* Compliance and auditing
* Troubleshoot errors

***

## Viewing API Logs [#viewing-api-logs]

### Accessing the Logs Dashboard [#accessing-the-logs-dashboard]

1. Open &#x2A;*[Settings](/dashboard/setup)**
2. In **API Access and Activity*&#x2A;, click &#x2A;*[API Audit Logs](/dashboard/organization/audit/api-logs)**
3. View recent API requests in chronological order
4. Use filters to narrow down results

### Log Information [#log-information]

Each log entry displays:

| Field          | Description                | Example                       |
| -------------- | -------------------------- | ----------------------------- |
| **Timestamp**  | When the request was made  | Dec 2, 2025 10:30:15 AM       |
| **Method**     | HTTP method used           | GET, POST, PUT, DELETE        |
| **Endpoint**   | API endpoint accessed      | `/v1/invoices`                |
| **Status**     | HTTP response code         | 200, 404, 500                 |
| **API Key**    | Which key made the request | Production API (pbk\_...x7f2) |
| **IP Address** | Request origin             | 192.168.1.1                   |

***

## Understanding Status Codes [#understanding-status-codes]

API logs include HTTP status codes indicating request outcomes:

### Success Codes (2xx) [#success-codes-2xx]

| Code    | Meaning    | Description                   |
| ------- | ---------- | ----------------------------- |
| **200** | OK         | Request successful            |
| **201** | Created    | Resource created successfully |
| **204** | No Content | Successful, no response body  |

### Client Error Codes (4xx) [#client-error-codes-4xx]

| Code    | Meaning           | Common Causes                        |
| ------- | ----------------- | ------------------------------------ |
| **400** | Bad Request       | Invalid request format or parameters |
| **401** | Unauthorized      | Invalid or missing API key           |
| **403** | Forbidden         | API key lacks required permissions   |
| **404** | Not Found         | Endpoint or resource doesn't exist   |
| **429** | Too Many Requests | Rate limit exceeded                  |

### Server Error Codes (5xx) [#server-error-codes-5xx]

| Code    | Meaning               | Action                              |
| ------- | --------------------- | ----------------------------------- |
| **500** | Internal Server Error | Contact support if persists         |
| **502** | Bad Gateway           | Temporary issue, retry with backoff |
| **503** | Service Unavailable   | System maintenance or overload      |

***

## Common Monitoring Patterns [#common-monitoring-patterns]

### Detecting Unusual Activity [#detecting-unusual-activity]

**High Volume of 401 Errors:**

* Possible unauthorized access attempts
* Check if API key was leaked
* Review IP addresses for patterns

**Spike in Requests:**

* Sudden increase in API calls
* May indicate runaway process
* Check for infinite loops in code

**Unusual IP Addresses:**

* Requests from unexpected locations
* May indicate compromised API key
* Consider geographic restrictions (Enterprise)

### Debugging Integration Issues [#debugging-integration-issues]

**Consistent 400 Errors:**

* Review request format and parameters
* Check API documentation for correct structure
* Validate JSON payloads

**Intermittent 429 Errors:**

* Rate limit being hit
* Implement exponential backoff
* Distribute load across multiple keys

**404 Errors:**

* Verify endpoint URL is correct
* Check API version in URL
* Ensure resource IDs exist

***

## Security Monitoring [#security-monitoring]

### Best Practices [#best-practices]

**Regular Reviews:**

* Review logs weekly for anomalies
* Set up alerts for suspicious patterns (Enterprise)
* Document normal usage patterns

**Key Rotation:**

* Rotate API keys every 90 days
* Monitor old key usage after rotation
* Revoke keys showing no activity

**Access Control:**

* Limit API key creation to admins only
* Review who has access to API keys
* Use separate keys per team/service

**Incident Response:**

1. Identify suspicious activity in logs
2. Immediately revoke compromised key
3. Create new API key with different name
4. Update affected services
5. Review logs for extent of breach
6. Document incident and response

<Callout type="warn">
  **Suspected Breach?** If you suspect API key compromise, revoke the key immediately and contact
  support.
</Callout>

***

## Troubleshooting [#troubleshooting]

<Accordions type="single">
  <Accordion title="No logs appearing" id="no-logs">
    **Problem**: API logs dashboard is empty.

    **Possible causes:**

    * No API keys have been used yet
    * You're viewing a different organization
    * Logs are outside retention period
    * You don't have permission to view logs (Guest role)

    **Solution**: Verify API keys exist and have been used. Make a test API request to generate logs.
  </Accordion>

  <Accordion title="Can't see old logs" id="old-logs">
    **Problem**: Logs from last month are missing.

    **Solution**: Check your plan's retention period:

    * Trial: 7 days
    * Pro: 30 days
    * Enterprise: 90 days

    Logs older than your retention period are automatically deleted. Upgrade for longer retention.
  </Accordion>

  <Accordion title="High error rate in logs" id="high-errors">
    **Problem**: Seeing many 4xx or 5xx errors.

    **Debugging steps:**

    1. Identify which API key is causing errors
    2. Check status code patterns (401, 400, 429, etc.)
    3. Review endpoint being called
    4. Examine request timing (is it consistent?)
    5. Check API documentation for correct usage
    6. Test endpoint manually using API docs
  </Accordion>

  <Accordion title="Suspicious activity detected" id="suspicious">
    **Problem**: Unusual IP addresses or request patterns.

    **Immediate actions:**

    1. Revoke the API key immediately
    2. Create a new API key
    3. Update services with new key
    4. Review extent of unauthorized access
    5. Change organization passwords if needed
    6. Contact support for security review (Enterprise)
  </Accordion>

  <Accordion title="Cannot access logs" id="no-access">
    **Problem**: "Insufficient permissions to view API logs" error.

    **Solution**: API logs require Admin or Member role. Guests cannot view logs. Contact your organization owner to upgrade your role.
  </Accordion>
</Accordions>

***

## Related Topics [#related-topics]

* [API Keys](/docs/api/api-keys) - Create and manage API authentication
* [API Introduction](/docs/api) - Getting started with PineBill API
* [Subscription Plans](/docs/subscription) - API usage limits and retention
* [API Documentation](https://api.pinebill.app/docs) - Complete API reference


# API Keys (/docs/api/api-keys)







## Quick Start [#quick-start]

API keys provide secure authentication for programmatic access to PineBill. Manage them from &#x2A;*[Settings](/dashboard/setup)** → **API Access and Activity*&#x2A; → &#x2A;*[API Keys](/dashboard/organization/apikeys)**.

<Callout type="info">
  **Plan Requirements**: API keys are available on **Pro** and **Enterprise** plans. Trial accounts
  get 2 keys for testing with 50 API calls/month.
</Callout>

***

## Creating API Keys [#creating-api-keys]

<Steps>
  <Step>
    ### 1. Access API Keys Dashboard [#1-access-api-keys-dashboard]

    <DocImage src="https://storage.pinebill.app/public/docs/image/My-Organization-12-02-2025_08_50_PM.webp" alt="Invoice Generator Overview" maxHeight="400px" className="w-full p-0" />

    1. Open &#x2A;*[Settings](/dashboard/setup)**
    2. In **API Access and Activity*&#x2A;, click &#x2A;*[API Keys](/dashboard/organization/apikeys)**
    3. Click **Create API Key** button
    4. API key creation dialog opens

    <Callout type="warn">
      **Admin Only**: Only organization admins can create API keys. Members and guests can view existing
      keys.
    </Callout>
  </Step>

  <Step>
    ### 2. Name Your Key [#2-name-your-key]

    * Enter a descriptive name (e.g., "Production Server", "Dev Environment")
    * Use names that identify the key's purpose or location
    * Maximum 100 characters

    **Good names:**

    * "Production API - Backend Server"
    * "Staging Environment"
    * "Mobile App Integration"

    **Avoid:**

    * "Key 1", "Test", "API Key"
  </Step>

  <Step>
    ### 3. Save and Copy Your Key [#3-save-and-copy-your-key]

    1. Click **Create API Key**
    2. Your API key is displayed **once only**
    3. Copy and store it securely immediately
    4. Click **Done** when saved

    <DocImage src="https://storage.pinebill.app/public/docs/image/My-Organization-12-02-2025_08_55_PM.webp" alt="Invoice Generator Overview" maxHeight="400px" className="w-full p-0" />

    <Callout type="error">
      **Critical**: The API key is shown only once. If you lose it, you must revoke and create a new
      key.
    </Callout>
  </Step>
</Steps>

***

## API Key Format [#api-key-format]

PineBill API keys follow this format:

```
pb_1234567890abcdefghijklmnopqrstuv
```

**Structure:**

* `pb_` - PineBill key prefix
* `[32 characters]` - Unique key identifier

***

## API Key Limits by Plan [#api-key-limits-by-plan]

| Plan           | Max API Keys | Monthly API Calls | Rate Limit |
| -------------- | ------------ | ----------------- | ---------- |
| **Trial**      | 2            | 50                | 60/minute  |
| **Solo**       | 0            | No API access     | N/A        |
| **Pro**        | 10           | 10,000            | 60/minute  |
| **Enterprise** | Unlimited    | Unlimited         | Custom     |

<Callout type="info">
  Upgrade to Pro or Enterprise to access API features. [View Plans →](/docs/subscription)
</Callout>

***

## Using API Keys [#using-api-keys]

### Authentication [#authentication]

Include your API key in the `X-API-Key` header:

```bash
curl -X GET https://api.pinebill.app/v1/invoices \
  -H "X-API-Key: pbk_live_your_api_key_here"
```

### JavaScript/Node.js Example [#javascriptnodejs-example]

```javascript
const response = await fetch("https://api.pinebill.app/v1/invoices", {
  headers: {
    "X-API-Key": process.env.PINEBILL_API_KEY,
    "Content-Type": "application/json",
  },
});

const data = await response.json();
```

### Python Example [#python-example]

```python
import requests

headers = {
    'X-API-Key': 'pbk_live_your_api_key_here',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.pinebill.app/v1/invoices',
    headers=headers
)

data = response.json()
```

***

## Revoking API Keys [#revoking-api-keys]

<Steps>
  <Step>
    ### 1. Access API Keys Dashboard [#1-access-api-keys-dashboard-1]

    1. Open &#x2A;*[Settings](/dashboard/setup)**
    2. Go to &#x2A;*[API Keys](/dashboard/organization/apikeys)**
    3. Find the key to revoke
    4. Click **Revoke** or **Delete** button

    <DocImage src="https://storage.pinebill.app/public/docs/image/My-Organization-12-02-2025_08_59_PM.png" alt="Invoice Generator Overview" maxHeight="400px" className="w-full p-0" />

    <Callout type="warn">
      **Owner Only**: Only organization owners can revoke API keys. This prevents unauthorized key
      deletion.
    </Callout>
  </Step>

  <Step>
    ### 2. Confirm Revocation [#2-confirm-revocation]

    1. Review the key name and last usage
    2. Confirm you want to revoke access
    3. Click **Revoke Key**
  </Step>
</Steps>

***

## Monitoring API Key Usage [#monitoring-api-key-usage]

### Usage Statistics [#usage-statistics]

View detailed usage for each API key:

1. Open &#x2A;*[Settings](/dashboard/setup)**
2. Navigate to &#x2A;*[API Keys](/dashboard/organization/apikeys)**
3. Click on a key to view details
4. See usage statistics for the last 30 days

**Available metrics:**

* Total requests in last 30 days
* Daily request chart
* Recent API calls (last 50)
* Status code distribution
* Most accessed endpoints

### API Audit Logs [#api-audit-logs]

Track all API activity across your organization:

* View all API requests from all keys
* Filter by date, endpoint, or status code
* Monitor for security issues
* Debug API integration problems

Open audit logs from &#x2A;*[Settings](/dashboard/setup)** → **API Access and Activity*&#x2A; → &#x2A;*[API Audit Logs](/dashboard/organization/audit/api-logs)**.

[Learn more about API Audit Logs →](/docs/api/api-audit)

***

## Troubleshooting [#troubleshooting]

<Accordions type="single">
  <Accordion title="API key not working" id="key-not-working">
    **Problem**: API requests return 401 Unauthorized.

    **Solutions**:

    * Verify key is copied correctly (no extra spaces)
    * Check key hasn't been revoked
    * Ensure using correct header: `X-API-Key`
    * Confirm key belongs to your organization
    * Check key hasn't expired (if expiration was set)
  </Accordion>

  <Accordion title="Cannot create API key" id="cannot-create">
    **Problem**: "Maximum number of API keys reached" error.

    **Solutions**:

    * Check your plan's API key limit
    * Revoke unused API keys
    * Upgrade to Pro (10 keys) or Enterprise (unlimited)
    * Contact support if you need more keys on your current plan
  </Accordion>

  <Accordion title="Rate limit exceeded" id="rate-limit">
    **Problem**: Getting 429 Too Many Requests errors.

    **Solutions**:

    * Implement exponential backoff in your code
    * Reduce request frequency
    * Distribute requests across multiple keys (if needed)
    * Upgrade to Enterprise for custom rate limits
    * Cache API responses when possible
  </Accordion>

  <Accordion title="Lost API key" id="lost-key">
    **Problem**: Can't find API key after creation.

    **Solution**:

    API keys are shown only once for security. You must:

    1. Revoke the lost key
    2. Create a new API key
    3. Update your application with the new key
    4. Store it securely this time (password manager, secrets vault)
  </Accordion>

  <Accordion title="Key shows in logs but not dashboard" id="missing-from-dashboard">
    **Problem**: API logs show requests from a key not listed in dashboard.

    **Possible causes**:

    * Key has been revoked (logs retain history)
    * You're viewing a different organization
    * Filter is hiding revoked keys

    **Solution**: Check "Show revoked keys" toggle in API Keys dashboard
  </Accordion>
</Accordions>

***

## Related Topics [#related-topics]

* [API Introduction](/docs/api) - Getting started with PineBill API
* [API Audit Logs](/docs/api/api-audit) - Monitor API usage and security
* [Subscription Plans](/docs/subscription) - API access requirements
* [API Documentation](https://api.pinebill.app/docs) - Complete API reference


# API Introduction (/docs/api)







## Quick Start [#quick-start]

PineBill provides a powerful RESTful API for programmatic access to invoicing, customer management, and analytics features. Integrate PineBill into your applications, automate workflows, and build custom solutions.

**Complete API documentation is available at: [api.pinebill.app/docs](https://api.pinebill.app/docs)**

***

## What You Can Do With PineBill API [#what-you-can-do-with-pinebill-api]

* **Generate Invoices**: Create and manage invoices programmatically
* **Customer Management**: Add, update, and retrieve customer information
* **Product**: Manage your product inventory via API

***

## Getting Started [#getting-started]

<Steps>
  <Step>
    ### 1. Choose Your Plan [#1-choose-your-plan]

    API access is available on **Pro** and **Enterprise** plans:

    * **Trial**: 50 API calls/month (testing only)
    * **Solo**: No API access
    * **Pro**: 10,000 API calls/month, up to 10 API keys
    * **Enterprise**: Unlimited API calls and keys

    [View Plans →](/docs/subscription)
  </Step>

  <Step>
    ### 2. Create an API Key [#2-create-an-api-key]

    1. Open &#x2A;*[Settings](/dashboard/setup)**
    2. In **API Access and Activity*&#x2A;, click &#x2A;*[API Keys](/dashboard/organization/apikeys)**
    3. Click **Create API Key**
    4. Copy and securely store your key (shown once)

    [Learn more about API Keys →](/docs/api/api-keys)

    <DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-04-15-2026_04_30_PM.png" alt="Invoice Generator Overview" maxHeight="400px" className="w-full p-0" />
  </Step>

  <Step>
    ### 3. Make Your First Request [#3-make-your-first-request]

    Use your API key in the `X-API-Key` header:

    ```bash
    curl -X GET https://api.pinebill.app/v1/invoices \
      -H "X-API-Key: pbk_live_your_api_key_here"
    ```
  </Step>

  <Step>
    ### 4. Explore the Documentation [#4-explore-the-documentation]

    Visit &#x2A;*[api.pinebill.app/docs](https://api.pinebill.app/docs)** for:

    * Interactive API explorer
    * Request/response examples
    * Authentication details
    * Rate limiting information
    * Error codes and handling
  </Step>
</Steps>

***

## API Features [#api-features]

### Authentication [#authentication]

All API requests require authentication using API keys:

* Include your API key in the `X-API-Key` header
* Keys are unique to your organization
* Revoke compromised keys immediately

### Rate Limiting [#rate-limiting]

Requests are rate-limited based on your subscription:

* 60 requests/minute per key for all plans,
* Rate limit headers included in responses

### Endpoints [#endpoints]

Core API endpoints include:

* `/v1/invoices` - Invoice management
* `/v1/customers` - Customer operations
* `/v1/products` - Product catalog
* `/v1/analytics` - Business metrics
* `/v1/pdf/generate` - PDF generation

**Full endpoint documentation**: [api.pinebill.app/docs](https://api.pinebill.app/docs)

***

## Security Best Practices [#security-best-practices]

<Callout type="warn">
  **Keep Your API Keys Secret**: Never expose API keys in client-side code, public repositories, or
  share them publicly.
</Callout>

**Recommended practices:**

* Store keys in environment variables
* Rotate keys periodically
* Use separate keys for development and production
* Monitor API usage for unusual activity
* Revoke unused or compromised keys immediately

[Learn about API Audit Logs →](/docs/api/api-audit)

***

## Support & Resources [#support--resources]

### Documentation [#documentation]

* **Interactive API Docs**: [api.pinebill.app/docs](https://api.pinebill.app/docs)
* **OpenAPI Spec**: Available at `/docs/json` endpoint

### Need Help? [#need-help]

* Review our comprehensive API documentation
* Check common error codes and solutions
* Contact support for Enterprise API assistance
* Report API issues via [GitHub](https://github.com/anthropics/claude-code/issues)

***

## Related Topics [#related-topics]

* [API Keys](/docs/api/api-keys) - Create and manage API authentication
* [API Audit Logs](/docs/api/api-audit) - Monitor API usage and security
* [Subscription Plans](/docs/subscription) - API access by plan tier


# Creating & Editing Events (/docs/calendar/events)





## Creating an event [#creating-an-event]

There are three ways to start a new event:

1. **New Event button** — opens a blank event form.
2. **Click an empty day** (Month view) — pre-fills that day as an all-day event.
3. **Click an empty time slot** (Week / Day view) — pre-fills that day and hour as a one-hour timed event.

<DocImage src="https://storage.pinebill.app/public/docs/image/Calendar-PineBill-07-11-2026_12_31_PM.png" alt="New event form" maxHeight="500px" className="w-full p-2" />

### Event fields [#event-fields]

| Field           | Required | Notes                                                              |
| --------------- | -------- | ------------------------------------------------------------------ |
| **Title**       | Yes      | Up to 200 characters                                               |
| **All day**     | No       | When on, the time fields are hidden and the event spans whole days |
| **Start date**  | Yes      | —                                                                  |
| **Start time**  | No       | Timed events only                                                  |
| **End date**    | Yes      | Must be on or after the start                                      |
| **End time**    | No       | Timed events only                                                  |
| **Location**    | No       | —                                                                  |
| **Color**       | No       | Choose from six preset colors                                      |
| **Description** | No       | Optional notes                                                     |

All times are interpreted in your organization's timezone.

<Callout type="info">
  On desktop, the new-event form floats over the calendar without a backdrop, so you can still see
  the calendar while filling it in.
</Callout>

***

## Viewing details [#viewing-details]

Click any item to open its **details**. What you see depends on the source:

* **Events** — location and description
* **Tasks** — status, project, assignee, and tracked time
* **Invoices** — status and amount
* **Projects** — status
* **Expenses** — amount

Read-only items include a link to open the source record.

<DocImage src="https://storage.pinebill.app/public/docs/image/Calendar-PineBill-07-11-2026_12_34_PM.png" alt="Event details popover" maxHeight="450px" className="w-full p-2" />

***

## Editing, rescheduling, and deleting [#editing-rescheduling-and-deleting]

These apply to your own **events** only:

* **Edit** — open the event's details and click **Edit**.
* **Reschedule** — drag an event to another day or time slot. Its duration is preserved.
* **Delete** — click **Delete** in the details view, or **right-click** the event for a quick delete. Deleting asks for confirmation and cannot be undone.

***

## "+N more" [#n-more]

When a day has more events than fit in the month grid, the extras collapse into a &#x2A;*"N+ More"** button. Click it to see the full list for that day.

<DocImage src="https://storage.pinebill.app/public/docs/image/Calendar-PineBill-07-11-2026_12_36_PM.png" alt="More events popover" maxHeight="400px" className="w-full p-2" />


# Calendar (/docs/calendar)





## Quick Start [#quick-start]

The Calendar brings everything with a date into one view — your own events plus deadlines and records pulled from across PineBill. Create events, drag them to reschedule, and filter by source.

Go to &#x2A;*[Dashboard](/dashboard)*&#x2A; -> &#x2A;*[Calendar](/dashboard/calendar)**.

{/* TODO: replace with real screenshot — full calendar (month view) */}

<DocImage src="https://storage.pinebill.app/public/docs/image/Calendar-PineBill-07-11-2026_12_26_PM.png" alt="Calendar month view" maxHeight="500px" className="w-full p-2" />

***

## What shows up on the calendar [#what-shows-up-on-the-calendar]

The calendar overlays five kinds of items, each with its own color:

| Source                | Color   | What it is                        | Editable here          |
| --------------------- | ------- | --------------------------------- | ---------------------- |
| **Events**            | Emerald | Events you create on the calendar | Yes                    |
| **Task Deadlines**    | Blue    | Due dates of your tasks           | No — opens the task    |
| **Invoice Due**       | Amber   | Invoice due dates                 | No — opens the invoice |
| **Project Deadlines** | Violet  | Project deadlines                 | No — opens the project |
| **Expenses**          | Rose    | Expense dates                     | No — opens the expense |

Only **Events** are created and edited on the calendar. The other four are read-only reflections of data elsewhere in the app — you can view their details and jump to the source record, but you change them from their own pages.

***

## Key Features [#key-features]

<Cards>
  <Card title="Views & Navigation" description="Switch between Month, Week, Day, and Agenda, and filter by source" href="/docs/calendar/views" />

  <Card title="Creating & Editing Events" description="Add, edit, reschedule, and delete calendar events" href="/docs/calendar/events" />

  <Card title="Calendar Settings" description="Set the day your week starts on" href="/docs/calendar/settings" />
</Cards>


# Calendar Settings (/docs/calendar/settings)





## Quick Start [#quick-start]

Go to &#x2A;*[Dashboard](/dashboard)*&#x2A; -> &#x2A;*[Setup](/dashboard/setup)*&#x2A; -> &#x2A;*[Calendar Settings](/dashboard/setup/calendar-settings)**.

<DocImage src="https://storage.pinebill.app/public/docs/image/Calendar-Settings-PineBill-07-11-2026_12_37_PM.png" alt="Calendar settings page" maxHeight="450px" className="w-full p-2" />

***

## Settings [#settings]

| Setting            | Options                     | Notes                                             |
| ------------------ | --------------------------- | ------------------------------------------------- |
| **Week starts on** | Sunday, Monday, or Saturday | Sets the first column in the Week and Month views |

<Callout type="info">
  Only the organization owner can change calendar settings. When you make a change, a save bar
  appears — click **Save changes** to apply it.
</Callout>


# Views & Navigation (/docs/calendar/views)





## Views [#views]

Switch views from the toolbar. Each shows a different span of time.

| View       | Shows                                                      |
| ---------- | ---------------------------------------------------------- |
| **Month**  | A full month grid — best for an overview                   |
| **Week**   | Seven days with an hourly time grid                        |
| **Day**    | A single day with an hourly time grid                      |
| **Agenda** | A scrolling list of what's scheduled over the next 30 days |

Expenses are not listed in the Agenda view.

{/* TODO: replace with real screenshot — toolbar view switcher */}

<DocImage src="https://storage.pinebill.app/public/docs/image/Calendar-PineBill-07-11-2026_12_29_PM.png" alt="Calendar view switcher" maxHeight="400px" className="w-full p-2" />

***

## Moving around [#moving-around]

* **Previous / Next arrows** move by one month, week, or day, depending on the current view.
* The **date label** in the toolbar lets you jump to a specific date.
* **Scroll** over the month grid to move to the next or previous month.
* The calendar opens on **today** each time.

***

## Filtering [#filtering]

Click **Filter** in the toolbar to choose which sources appear. Each source shows a live count for the current period. When something is hidden, a badge on the Filter button shows how many sources are turned off.

<DocImage src="https://storage.pinebill.app/public/docs/image/Calendar-PineBill-07-11-2026_12_30_PM.png" alt="Calendar source filter" maxHeight="400px" className="w-full p-2" />


# Adding New Customers (/docs/customers/adding-customers)







## Quick Start [#quick-start]

Adding customers to PineBill is straightforward. Navigate to the &#x2A;*[Customers](/dashboard/customers)** page from your dashboard and click the **Create Customer** button to get started.

<DocImage src="https://storage.pinebill.app/public/docs/image/Customers-List-PineBill-04-15-2026_03_54_PM.png" alt="Invoice Generator Overview" maxHeight="500px" className="w-full p-0" />

## Customer Fields [#customer-fields]

| Field         | Required | Description                                                                                  | Max Length | Notes                                                                                           |
| ------------- | -------- | -------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------- |
| Customer Name | Yes      | The full name or business name of your customer                                              | 100 chars  | -                                                                                               |
| Customer ID   | Yes      | A unique identifier for this customer (e.g., tax number, internal code)                      | 50 chars   | Must be unique across your organization. Used to quickly find and reference the customer        |
| Email Address | No       | Customer's email for sending invoices and communications                                     | -          | Must be valid email format (e.g., `customer@company.com`)                                       |
| Phone Number  | No       | Customer's contact phone number                                                              | 30 chars   | Any format accepted - no specific format enforced                                               |
| Address       | No       | Customer's billing or business address                                                       | 200 chars  | Use the multi-line text area for complete addresses                                             |
| ZIP Code      | No       | Customer's postal or ZIP code                                                                | 20 chars   | -                                                                                               |
| Country       | No       | Customer's country                                                                           | -          | Must use ISO 3166-1 country names. Select from dropdown (e.g., "United States", "Germany")      |
| Website       | No       | Customer's website URL                                                                       | -          | Must be a valid URL (e.g., `https://example.com`)                                               |
| Tax ID / VAT  | No       | Customer's tax identification or VAT number                                                  | 50 chars   | Any format accepted (e.g., `US12-3456789`, `DE123456789`)                                       |
| Timezone      | No       | Customer's timezone in IANA format                                                           | -          | Defaults to UTC. Examples: `America/New_York`, `Europe/London`. Dropdown shows timezone offsets |
| Description   | No       | Additional notes about the customer (e.g., payment terms, preferences, special requirements) | 500 chars  | For internal use only                                                                           |

## Step-by-Step Guide [#step-by-step-guide]

### 1. Access the Customer Creation Form [#1-access-the-customer-creation-form]

1. Navigate to &#x2A;*[Dashboard](/dashboard)*&#x2A; → &#x2A;*[Customers](/dashboard/customers)**
2. Click the **Create Customer** button (top-right corner with plus icon)
3. The "Create New Customer" dialog will open

### 2. Fill in Customer Details [#2-fill-in-customer-details]

Fill out the form with your customer's information:

```
Name: Acme Corporation *
Customer ID: ACME-001 *
Email Address: billing@acme.com
Phone Number: +1 (555) 123-4567
ZIP Code: 10001
Country: United States
Website: https://acme.com
Tax ID / VAT: US12-3456789
Timezone: America/New_York
Address: 123 Main Street
         Suite 100
         New York, NY
Description: Premium customer - Net 30 payment terms
```

Fields marked with \* are required.

<DocImage src="https://storage.pinebill.app/public/docs/image/Customers-List-PineBill-12-01-2025_11_50_AM.webp" alt="Invoice Generator Overview" maxHeight="500px" className="w-full p-0" />

### 3. Review and Submit [#3-review-and-submit]

1. Double-check that the **Customer ID** is correct (it must be unique)
2. Verify the email address is accurate for invoice delivery
3. Click **Create Customer** to save
4. You'll see a success notification when the customer is created

## After Creating a Customer [#after-creating-a-customer]

Once a customer is created, you can:

1. **View Customer Details**: Click on any customer in the list to see full information
2. **[Edit Customer](/docs/customers/editing-customer)**: Update customer details anytime by clicking the edit button
3. **Search and Filter**: Find customers quickly using the search bar

## Additional Notes [#additional-notes]

* Customers are scoped to your organization - team members can access all organization customers
* You cannot delete customers who have existing invoices (to maintain data integrity)
* Only organization owners have permission to delete customers

## Common Errors and Solutions [#common-errors-and-solutions]

<Accordions type="single">
  <Accordion title="Customer with this identifier already exists" id="duplicate-identifier">
    **Problem**: The Customer ID you entered is already used by another customer in your organization.

    **Solution**: Choose a different unique identifier. You can view all existing customers on the Customers page to check which IDs are already in use.
  </Accordion>

  <Accordion title="Invalid email address" id="invalid-email">
    **Problem**: The email format is not valid.

    **Solution**: Ensure the email follows the format `username@domain.com` with no spaces or special characters except @ and periods.
  </Accordion>

  <Accordion title="Invalid country" id="invalid-country">
    **Problem**: The country name doesn't match ISO 3166-1 standards.

    **Solution**: Use the country dropdown selector instead of typing manually. This ensures the country name is valid.
  </Accordion>

  <Accordion title="Invalid IANA timezone" id="invalid-timezone">
    **Problem**: The timezone format is not recognized.

    **Solution**: Use the timezone dropdown selector which provides all valid IANA timezones with their current offsets.
  </Accordion>
</Accordions>


# Bulk Import Customers (/docs/customers/bulk-import)





## Overview [#overview]

You can import up to **5,000 customers** at once by uploading a CSV file. The import wizard walks you through four steps: upload, column mapping, preview, and results.

***

## Starting an Import [#starting-an-import]

Navigate to &#x2A;*[Customers](/dashboard/customers)** and click the **Import** button next to the Create Customer button.

<DocImage src="https://storage.pinebill.app/public/docs/image/Customers-List-PineBill-02-09-2026_11_07_AM.webp" alt="Import button on customers page" maxHeight="400px" className="w-full p-0" />

***

## Step 1: Upload CSV [#step-1-upload-csv]

Upload your CSV file or download a template to get started.

* Click **Download Template** to get a pre-formatted CSV with the correct headers
* Drag and drop your CSV file or click to browse
* The file must be a valid `.csv` file with headers in the first row
* Maximum **5,000 rows** per import

<DocImage src="https://storage.pinebill.app/public/docs/image/Customers-List-PineBill-02-09-2026_11_14_AM.webp" alt="Upload step of the import dialog" maxHeight="500px" className="w-full p-0" />

### CSV Template [#csv-template]

The template includes these columns:

| Column      | Required                              | Example                                     |
| ----------- | ------------------------------------- | ------------------------------------------- |
| Name        | <u className="text-primary">Yes\*</u> | Acme Corp                                   |
| Identifier  | <u className="text-primary">Yes\*</u> | CUST-001                                    |
| Email       | No                                    | [contact@acme.com](mailto:contact@acme.com) |
| Phone       | No                                    | +1-555-123-4567                             |
| Address     | No                                    | 123 Main St                                 |
| Zip Code    | No                                    | 10001                                       |
| Country     | No                                    | South Korea                                 |
| Description | No                                    | Enterprise client                           |
| Website     | No                                    | [https://acme.com](https://acme.com)        |
| Tax ID      | No                                    | US12-3456789                                |

**Sample CSV:**

```csv
Name,Identifier,Email,Phone,Address,Zip Code,Country,Description,Website,Tax ID
Acme Corporation,ACME-001,contact@acme.com,+1-555-100-2000,123 Main St,10001,United States of America,Enterprise client,https://acme.com,US12-3456789
GlobalTech Solutions,GT-002,info@globaltech.io,+44-20-7946-0958,45 Oxford Street,W1D 2DZ,United Kingdom,Technology partner,https://globaltech.io,GB123456789
Berlin Design Studio,BDS-003,hello@berlindesign.de,+49-30-12345678,Friedrichstr. 100,10117,Germany,Creative agency,https://berlindesign.de,DE987654321
```

***

## Step 2: Map Columns [#step-2-map-columns]

Map your CSV columns to customer fields. The wizard auto-detects common column names (e.g., "customer name", "customer id", "email address"), but you can adjust the mapping manually.

* Required fields (**Name**, **Identifier**) must be mapped before proceeding
* Unmapped optional fields will be skipped
* Click **Reset** to restore auto-detected mappings

<DocImage src="https://storage.pinebill.app/public/docs/image/Customers-List-PineBill-02-09-2026_11_16_AM.webp" alt="Column mapping step" maxHeight="500px" className="w-full p-0" />

***

## Step 3: Preview [#step-3-preview]

Review parsed data before importing. The preview shows:

* Total rows parsed
* Valid rows (will be imported)
* Invalid rows with specific error details per field

Only valid rows are imported. Fix any issues in your CSV and re-upload if needed.

<DocImage src="https://storage.pinebill.app/public/docs/image/Customers-List-PineBill-02-09-2026_11_17_AM.webp" alt="Preview step showing valid and invalid rows" maxHeight="500px" className="w-full p-0" />

***

## Step 4: Results [#step-4-results]

After clicking **Import**, the wizard processes your data in batches of 100 rows and shows a progress indicator. Once complete, you'll see:

* Number of customers created
* Number of rows skipped (duplicates or errors)
* Specific error messages for failed rows

<DocImage src="https://storage.pinebill.app/public/docs/image/Customers-List-PineBill-02-09-2026_11_18_AM.webp" alt="Import results summary" maxHeight="500px" className="w-full p-0" />

***

## Field Details [#field-details]

### Identifier [#identifier]

Each customer must have a unique **Identifier** (e.g., tax number, account number). If an identifier already exists in your organization, that row will be skipped during import.

### Country [#country]

Country values must match ISO 3166-1 country names (e.g., "United States of America", "Germany", "Japan"). Invalid country names will cause the row to fail validation.

### Email [#email]

Must be a valid email format. Empty values are accepted (the field is optional).

### Website [#website]

Must be a valid URL (e.g., `https://example.com`). Empty values are accepted.

### Tax ID [#tax-id]

Customer's tax identification or VAT number (up to 50 characters). Any format is accepted. Empty values are accepted.

***

## Related Topics [#related-topics]

* [Adding Customers](/docs/customers/adding-customers) - Add customers one by one
* [Customer Details](/docs/customers/customer-details) - View imported customer information
* [Bulk Import Products](/docs/products/bulk-import) - Import products via CSV


# Customer Details Page (/docs/customers/customer-details)





<DocImage src="https://storage.pinebill.app/public/docs/image/Customers-List-PineBill-12-01-2025_07_19_PM.webp" alt="Invoice Generator Overview" maxHeight="500px" className="w-full p-0" />

## Customer Details [#customer-details]

The customer details section displays all information about the customer. This information is organized into a grid layout showing key fields and contact information.

### Customer Information Fields [#customer-information-fields]

| Field          | Description                                          | Display Notes                                     |
| -------------- | ---------------------------------------------------- | ------------------------------------------------- |
| **Name**       | Customer's full name or business name                | Displayed in page header and details section      |
| **Identifier** | Unique customer ID (e.g., tax number, internal code) | Shown with hash icon for easy identification      |
| **Email**      | Customer's email address                             | Shown with mail icon, displays "—" if empty       |
| **Phone**      | Customer's contact phone number                      | Shown with phone icon, displays "—" if empty      |
| **Country**    | Customer's country location                          | Only displayed if country is specified            |
| **Website**    | Customer's website URL                               | Displayed as a clickable link, only shown if set  |
| **Tax ID**     | Customer's tax ID or VAT number                      | Only displayed if tax ID is specified             |
| **Timezone**   | Customer's timezone in IANA format                   | Includes hover tooltip showing time offset        |
| **Created**    | Date when customer record was created                | Formatted as readable date (e.g., "Jan 15, 2025") |

### Address Information [#address-information]

If the customer has address information, it appears in a separate section below the main details:

* **Address** - Full street address (supports multi-line)
* **ZIP Code** - Postal or ZIP code

Address fields only display if at least one address field (address or zip code) is present.

***

## Customer Invoices [#customer-invoices]

<DocImage src="https://storage.pinebill.app/public/docs/image/Customers-List-PineBill-12-01-2025_07_25_PM.webp" alt="Invoice Generator Overview" maxHeight="500px" className="w-full p-0" />

The invoices section shows all invoices associated with this customer in a comprehensive table view.

### Invoice Table Columns [#invoice-table-columns]

| Column          | Information                                                     |
| --------------- | --------------------------------------------------------------- |
| **Invoice #**   | Unique invoice number in monospace font for easy identification |
| **Amount**      | Total invoice amount with currency code                         |
| **Status**      | Current invoice status displayed as a colored badge             |
| **Issued Date** | Date when the invoice was created (e.g., "Dec 1, 2024")         |
| **Actions**     | Eye icon button to view full invoice details                    |

### Viewing Invoices [#viewing-invoices]

Click the eye icon in the Actions column to navigate to the full invoice details page for that specific invoice.

### When No Invoices Exist [#when-no-invoices-exist]

If the customer doesn't have any invoices yet, you'll see a placeholder message:

* File icon
* "No invoices" heading
* Message explaining the customer has no invoices

This is common for newly created customers.

***

## Invoice Statistics (Right Sidebar) [#invoice-statistics-right-sidebar]

<DocImage src="https://storage.pinebill.app/public/docs/image/Customers-List-PineBill-12-01-2025_07_41_PM.png" alt="Invoice Generator Overview" maxHeight="500px" className="w-full p-0" />

The Invoice Stats card provides quick metrics about the customer's invoice activity.

### Displayed Metrics [#displayed-metrics]

**Total Invoices:**
Shows the count of all invoices for this customer. The number is displayed prominently in large text.

**Total Value:** (shown when invoices exist)
Sum of all invoice amounts for this customer, converted to your organization's default currency using current exchange rates. If the customer has invoices in multiple currencies (e.g., EUR, GBP, USD), they are all converted and totaled in your organization's currency.

**Average Invoice:** (shown when invoices exist)
Average invoice amount calculated by dividing total value by invoice count. This is calculated in your organization's default currency after currency conversion. Helps understand typical transaction size for this customer.

### Understanding the Stats [#understanding-the-stats]

* Stats update automatically when invoices are created or deleted
* All amounts are calculated in real-time from actual invoice data
* Currency conversion uses current exchange rates to ensure accurate totals
* These metrics help identify your highest-value customers across all currencies

***

## Deleting Customers [#deleting-customers]

The delete button permanently removes the customer record from your organization.

### Before You Delete [#before-you-delete]

**Important considerations:**

* Deletion is permanent and cannot be undone
* You cannot delete customers who have existing invoices
* Only organization owners can delete customers
* All customer data will be permanently removed

<Callout type="warning">
  If the customer has invoices, the delete button will be disabled with a tooltip explaining the
  restriction.
</Callout>

***

## Related Topics [#related-topics]

* [Adding New Customers](/docs/customers/adding-customers) - Creating customer records
* [Editing Customers](/docs/customers/editing-customer) - Updating customer information
* [Invoice Details](/docs/invoices/invoice-details) - Understanding invoice information


# Editing Customers (/docs/customers/editing-customer)







## Quick Start [#quick-start]

You can update customer information anytime from the Customers page. All customer fields can be modified except for the internal database ID.

## Step-by-Step Guide [#step-by-step-guide]

### 1. Open the Edit Dialog [#1-open-the-edit-dialog]

1. Go to the [Customers page](/dashboard/customers)
2. Locate the customer using search or pagination
3. Click the Edit button in the customer's row

<DocImage src="https://storage.pinebill.app/public/docs/image/Customers-List-PineBill-12-01-2025_11_58_AM.png" alt="Invoice Details Page Overview" maxHeight="500px" className="w-full p-0" />

### 2. Modify Customer Information [#2-modify-customer-information]

The edit dialog will display the customer's current information pre-filled in all fields:

* Update any fields you need to change
* Leave fields unchanged if they're correct
* Use the dropdown selectors for Country and Timezone to ensure valid values

### 3. Save Changes [#3-save-changes]

1. Review your changes
2. Click **Update Customer** to save
3. You'll see a success notification when the update completes
4. The customer list will automatically refresh with the updated information

<DocImage src="https://storage.pinebill.app/public/docs/image/Customers-List-PineBill-12-01-2025_07_14_PM.webp" alt="Invoice Details Page Overview" maxHeight="500px" className="w-full p-0" />

## Editable Fields [#editable-fields]

You can modify all the same fields available during customer creation:

| Field         | Can Edit | Notes                                                                      |
| ------------- | -------- | -------------------------------------------------------------------------- |
| Customer Name | Yes      | Update the customer's full name or business name                           |
| Customer ID   | Yes      | Change the unique identifier (must remain unique across your organization) |
| Email Address | Yes      | Update or add email address for invoicing                                  |
| Phone Number  | Yes      | Update or add phone number                                                 |
| Address       | Yes      | Update billing or business address                                         |
| ZIP Code      | Yes      | Update postal/ZIP code                                                     |
| Country       | Yes      | Change country (use dropdown for valid ISO 3166-1 names)                   |
| Website       | Yes      | Update or add website URL                                                  |
| Tax ID / VAT  | Yes      | Update or add tax identification / VAT number                              |
| Timezone      | Yes      | Update timezone (IANA format)                                              |
| Description   | Yes      | Modify internal notes and customer details                                 |

## Additional Notes [#additional-notes]

* Edits take effect immediately after saving
* Customer edits don't affect existing invoice data (invoices store a snapshot)

## Common Errors and Solutions [#common-errors-and-solutions]

<Accordions type="single">
  <Accordion title="Customer with this identifier already exists" id="duplicate-identifier-edit">
    **Problem**: The Customer ID you're trying to change to is already used by another customer.

    **Solution**: Choose a different unique identifier. Check existing customers to see which IDs are in use.
  </Accordion>

  <Accordion title="Customer not found" id="customer-not-found">
    **Problem**: The customer you're trying to edit has been deleted or doesn't exist.

    **Solution**: Return to the Customers page and verify the customer still exists. Refresh your browser if needed.
  </Accordion>

  <Accordion title="Invalid email address" id="invalid-email-edit">
    **Problem**: The email format is not valid.

    **Solution**: Ensure the email follows the format `username@domain.com` with no spaces or invalid characters.
  </Accordion>

  <Accordion title="Changes not saving" id="changes-not-saving">
    **Problem**: When you click Update Customer, nothing happens or you get an error.

    **Solution**: Check that required fields (Name and Customer ID) are filled. Look for validation error messages in red below fields. Ensure your internet connection is stable.
  </Accordion>
</Accordions>


# Employees (/docs/employees)







## Quick Start [#quick-start]

Employees represent your organization's staff members. Track who creates invoices and analyze employee performance in analytics. Open the page from &#x2A;*[Settings](/dashboard/setup)** → **Organization Management*&#x2A; → &#x2A;*[Employees](/dashboard/organization/employees)**.

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-04-15-2026_04_33_PM.png" alt="Employees list page" maxHeight="500px" className="w-full p-0" />

***

## Employee Fields [#employee-fields]

| Field        | Required | Max Length | Description                                     |
| ------------ | -------- | ---------- | ----------------------------------------------- |
| Employee ID  | Yes      | 50 chars   | Unique identifier (e.g., EMP001)                |
| Full Name    | Yes      | 100 chars  | Employee's full name                            |
| Email        | No       | -          | Email address (must be valid format)            |
| Phone        | No       | 50 chars   | Phone number (any format)                       |
| Position     | No       | 100 chars  | Job title (e.g., Sales Manager)                 |
| Department   | No       | 100 chars  | Department name (select existing or enter new)  |
| Hire Date    | No       | -          | Date when employee was hired                    |
| Link to User | No       | -          | Connect employee to organization member account |

***

## Creating Employees [#creating-employees]

<Steps>
  <Step>
    ### Open Create Dialog [#open-create-dialog]

    1. Open &#x2A;*[Settings](/dashboard/setup)**
    2. In **Organization Management*&#x2A;, click &#x2A;*[Employees](/dashboard/organization/employees)**
    3. Click **Add Employee** button (top-right)
    4. Create employee dialog opens

    <DocImage src="https://storage.pinebill.app/public/docs/image/My-Organization-12-02-2025_08_13_PM.png" alt="Add employee button location" maxHeight="400px" className="w-full p-0" />
  </Step>

  <Step>
    ### Fill Employee Details [#fill-employee-details]

    **Required Fields:**

    ```
    Employee ID: EMP001 *
    Full Name: John Doe *
    ```

    **Optional Fields:**

    ```
    Email: john.doe@company.com
    Phone: +1 (555) 123-4567
    Position: Sales Manager
    Department: Sales (select or type new)
    Hire Date: [Select from calendar]
    Link to User: [Select organization member]
    ```

    <DocImage src="https://storage.pinebill.app/public/docs/image/My-Organization-12-02-2025_08_15_PM.webp" alt="Employee creation form" maxHeight="450px" className="w-full p-0" />

    **Department Selection:**

    * Dropdown shows existing departments
    * Select "Custom Department" to enter a new one
    * Type new department name in text field

    **Link to User:**

    * Links employee record to organization member
    * Enables user to be assigned to invoices
    * Shows member's name and email in dropdown
    * Optional - employees don't need to be linked
  </Step>

  <Step>
    ### Save Employee [#save-employee]

    1. Click **Create Employee** button
  </Step>
</Steps>

***

## Employee List [#employee-list]

Table showing all employees:

| Column      | Information                   |
| ----------- | ----------------------------- |
| Employee ID | Unique identifier             |
| Name        | Full name                     |
| Email       | Email address (if set)        |
| Phone       | Phone number (if set)         |
| Position    | Job title (if set)            |
| Department  | Department name (if set)      |
| Status      | Active or Inactive badge      |
| Actions     | View details, edit, or delete |

<DocImage src="https://storage.pinebill.app/public/docs/image/My-Organization-12-02-2025_08_16_PM.png" alt="Employees list table" maxHeight="500px" className="w-full p-0" />

***

## Managing Employees [#managing-employees]

### Viewing Employee Details [#viewing-employee-details]

1. Click employee row or **View** icon
2. Opens employee details page
3. Shows:
   * Employee information
   * Monthly performance stats
   * Invoice history table
   * Total invoices created
   * Total revenue generated

<DocImage src="https://storage.pinebill.app/public/docs/image/My-Organization-12-02-2025_08_18_PM.webp" alt="Employee details and performance" maxHeight="500px" className="w-full p-0" />

**Monthly Stats:**

* Revenue by month
* Invoice count by month
* Conversion rate (paid/total invoices)
* Visual charts

**Invoice Table:**

* All invoices assigned to this employee
* Filter by status, date, amount
* Sort by any column
* Click invoice to view details

### Editing Employees [#editing-employees]

1. Click **Edit** icon on employee row
2. Edit dialog opens with current data
3. Update any fields
4. Click **Save Changes**

All fields can be edited including:

* Employee ID
* Name
* Contact information
* Department
* Hire date
* Linked user

**Note**: Editing employee ID doesn't affect existing invoice assignments.

### Deleting Employees [#deleting-employees]

**Important behavior:**

**If employee has NO assigned invoices:**

* Employee is permanently deleted
* Cannot be undone
* Removed from the system

**If employee HAS assigned invoices:**

* Employee is deactivated instead (not deleted)
* Status changes to "Inactive"
* Remains in the database
* Invoices keep the employee reference
* Appears in historical data and analytics

**To delete:**

1. Click **Delete** icon
2. Confirm deletion
3. System checks for assigned invoices:
   * No invoices: Deleted permanently
   * Has invoices: Deactivated

<DocImage src="https://storage.pinebill.app/public/docs/image/My-Organization-12-02-2025_08_19_PM.webp" alt="Delete employee confirmation" maxHeight="400px" className="w-full p-0" />

***

## Linking Employees to Users [#linking-employees-to-users]

### Purpose [#purpose]

Linking connects an employee record to an organization member account:

* Enables assigning the user to invoices
* Tracks which member created which invoice
* Powers employee performance analytics
* Shows employee in invoice assignment dropdown

### How to Link [#how-to-link]

**When Creating Employee:**

1. In create dialog, find "Link to User" field
2. Dropdown shows all organization members
3. Select a member
4. Employee is linked to that user account

**When Editing Employee:**

1. Edit existing employee
2. Change "Link to User" field
3. Can link, unlink, or change linked user

***

## Common Errors [#common-errors]

<Accordions type="single">
  <Accordion title="Employee ID is required" id="id-required">
    **Problem**: Employee ID field is empty.

    **Solution**: Enter a unique identifier (e.g., EMP001, JD-2024, etc.).
  </Accordion>

  <Accordion title="Employee ID already exists" id="duplicate-id">
    **Problem**: Another employee already has this ID.

    **Solution**: Choose a different Employee ID. Each ID must be unique within your organization.
  </Accordion>

  <Accordion title="Full name is required" id="name-required">
    **Problem**: Name field is empty.

    **Solution**: Enter the employee's full name.
  </Accordion>

  <Accordion title="Invalid email address" id="invalid-email">
    **Problem**: Email format is incorrect.

    **Solution**: Enter a valid email (e.g., [john@company.com](mailto:john@company.com)) or leave empty.
  </Accordion>

  <Accordion title="Cannot delete employee" id="cannot-delete">
    **Problem**: Employee has assigned invoices.

    **Solution**: The system automatically deactivates the employee instead of deleting. This preserves historical invoice data. Check the employee's status - it should be "Inactive" now.
  </Accordion>
</Accordions>

***

## Related Topics [#related-topics]

* [Creating Invoices](/docs/invoices/creating-invoices) - Assign employees to invoices
* [Analytics](/docs/analytics) - View employee performance (Enterprise)
* [Organization](/docs/organization) - Manage team members


# Converting Estimates to Invoices (/docs/estimates/converting-to-invoice)





## Overview [#overview]

One of PineBill's most powerful features is the ability to convert an accepted estimate directly into an invoice. This eliminates duplicate data entry and ensures consistency between what was quoted and what is billed.

<DocImage src="https://storage.pinebill.app/public/docs/image/Estimate-Details-PineBill-03-19-2026_12_42_PM.png" alt="Convert to Invoice Button" maxHeight="400px" className="w-full p-0" />

***

## Requirements [#requirements]

Before you can convert an estimate to an invoice:

| Requirement      | Details                                                          |
| ---------------- | ---------------------------------------------------------------- |
| **Status**       | Estimate must be in **ACCEPTED** status                          |
| **Subscription** | Your organization must have available invoice slots in your plan |

<Callout type="info">
  Only estimates with ACCEPTED status show the "Convert to Invoice" button. Update the estimate
  status first if needed.
</Callout>

***

## How to Convert [#how-to-convert]

1. Open the estimate you want to convert
2. Click the **Convert to Invoice** button in the page header
3. Confirm the conversion in the dialog
4. You'll be redirected to the newly created invoice

<DocImage src="https://storage.pinebill.app/public/docs/image/Estimate-Details-PineBill-03-19-2026_12_43_PM.png" alt="Convert to Invoice Confirmation" maxHeight="400px" className="w-full p-0" />

***

## What Gets Copied [#what-gets-copied]

When you convert an estimate to an invoice, the following data is automatically transferred:

| Data                | Copied | Notes                                  |
| ------------------- | ------ | -------------------------------------- |
| **Line Items**      | Yes    | All products/services with quantities  |
| **Customer**        | Yes    | Same customer linked to the invoice    |
| **Pricing**         | Yes    | Unit prices, quantities, totals        |
| **Tax Settings**    | Yes    | Tax rate, type, and included/excluded  |
| **Discount**        | Yes    | Discount amount carried over           |
| **Shipping**        | Yes    | Shipping costs carried over            |
| **Currency**        | Yes    | Same currency used                     |
| **Custom Fields**   | Yes    | All custom label-value pairs           |
| **Terms**           | Yes    | Payment terms carried over             |
| **End Message**     | Yes    | Custom message carried over            |
| **Employee**        | Yes    | Assigned employee linked to invoice    |
| **Invoice Number**  | No     | A new invoice number is generated      |
| **Dates**           | No     | New issue date and due date are set    |
| **Payment Methods** | No     | Add payment methods on the new invoice |

***

## What Happens After Conversion [#what-happens-after-conversion]

### The Estimate [#the-estimate]

* Status changes to **CONVERTED** automatically
* The estimate is **locked** — you can no longer change its status
* A link to the created invoice appears on the estimate details page
* The estimate remains in your list for reference and audit trail

### The Invoice [#the-invoice]

* A new invoice is created with **DRAFT** status
* All estimate data is copied (see table above)
* A new invoice number is generated based on your [Invoice Settings](/docs/invoices/invoice-settings)
* You're redirected to the new invoice details page
* The invoice shows it was created from an estimate (source link)

### Subscription Limits [#subscription-limits]

The conversion counts toward your organization's invoice limit. If you've reached your plan's invoice limit, the conversion will be blocked and you'll need to upgrade your subscription.

***

## Related Topics [#related-topics]

* [Estimate Statuses](/docs/estimates/estimate-statuses) - Understanding status transitions
* [Estimate Details](/docs/estimates/estimate-details) - Managing estimate information
* [Creating Invoices](/docs/invoices/creating-invoices) - Invoice creation guide
* [Invoice Details](/docs/invoices/invoice-details) - Managing the created invoice


# Creating Estimates (/docs/estimates/creating-estimates)





## Quick Start [#quick-start]

Access the estimate generator from your dashboard by clicking "Create Estimate" on the Estimates page or "Plus" button on the sidebar.

<DocImage src="https://storage.pinebill.app/public/docs/image/Estimates-PineBill-04-15-2026_03_50_PM.png" alt="Estimate Generator Overview" maxHeight="500px" className="w-full p-2" />

***

## User Interface [#user-interface]

The estimate generator interface consists of 3 main regions:

1. **Parameters Area**: Tabbed interface where you configure estimate details (Customer, Products, Estimate Details, Company Info)
2. **Preview Area**: Visual preview of your estimate (HTML preview, not real-time PDF generation)
3. **Toolbar Area**: Top bar with Create Estimate button, options menu, and template/format settings

<DocImage src="https://storage.pinebill.app/public/docs/image/Create-Estimate-PineBill-03-19-2026_12_16_PM.png" alt="Estimate Generator UI Regions" maxHeight="450px" className="w-full p-2" />

***

## Toolbar Features [#toolbar-features]

The toolbar at the top of the estimate generator provides quick access to display options and the create button.

<DocImage src="https://storage.pinebill.app/public/docs/image/Create-Estimate-PineBill-03-19-2026_12_18_PM.png" alt="Estimate Generator Toolbar" maxHeight="300px" className="w-full p-2" />

### Live Preview [#live-preview]

Toggle live preview from the options menu to see your estimate in real-time as you make changes.

### Templates [#templates]

Select your estimate template from the options menu (top right):

* **Classic**: Clean, traditional design
* **Bold Professional**: Contemporary with bold accents
* **Mono**: Minimalist, monospace style
* **Startup Modern**: Sleek, modern look for startups

Each template includes all the same information with different visual styling. [Learn more about templates](/docs/invoices/invoice-templates).

### Date Formats [#date-formats]

Select date format from options menu. Available formats:

| Format 1   | Format 2       | Format 3     |
| ---------- | -------------- | ------------ |
| MM/DD/YYYY | Month DD, YYYY | Mon DD, YYYY |
| DD/MM/YYYY | DD Month YYYY  | DD Mon YYYY  |
| YYYY-MM-DD |                |              |

### Estimate Language [#estimate-language]

Select the language for your estimate PDF labels and text. This controls how section titles, column headers, and standard text appear on the generated PDF.

<Callout type="info">
  The language setting only affects PDF labels (like "Estimate", "Valid Until", "Total"). Your
  custom content such as product names, descriptions, and messages remains unchanged.
</Callout>

Set your default language in [Estimate Settings](/docs/estimates/estimate-settings) to save time when creating estimates.

***

## Step-by-Step Guide [#step-by-step-guide]

## Requirements [#requirements]

To create an estimate you must have:

| Requirement           | Status      | Details                  |
| --------------------- | ----------- | ------------------------ |
| Customer              | Required    | At least one customer    |
| Product/Service Items | Required    | At least one line item   |
| Estimate Number       | Auto-filled | Automatically generated  |
| Issue Date            | Auto-filled | Defaults to current date |

The estimate generator has 4 tabs. Fill them out to create your estimate.

### 1. Products/Services (Required) [#1-productsservices-required]

Add items to your estimate using the **inline product row** at the bottom of the products table:

* **Type to Search**: Start typing a product name in the inline row. An autocomplete dropdown appears with matching products from your catalog. Recent products are shown automatically when you click the field.
* **Select from Catalog**: Click a product in the dropdown to instantly add it to your estimate with its saved name, model, and price.
* **Create Inline Temporary Item**: Type a new product name that doesn't match any catalog product, then fill in the model, quantity, and price fields in the same row. Press **Enter** or click outside to add it. Temporary items are not saved to your catalog.
* **[Browse All Products](/docs/products/product-selection)**: Click "Browse All Products" at the bottom of the autocomplete dropdown to open the full product selector with filters, categories, and multi-select.

<DocImage src="https://storage.pinebill.app/public/docs/image/Create-Estimate-PineBill-03-19-2026_12_20_PM.png" alt="Products Tab" maxHeight="400px" className="w-full p-2" />

### Selected Product Features: [#selected-product-features]

* **Drag to Reorder**: Click and drag items to change their order on the estimate
* **Inline Editing**: Click any quantity or unit price to edit it directly in the table. For temporary items, you can also click to edit the name and model.

**Additional Costs:**

* **Shipping**: Add delivery or shipping costs
* **Discount**: Apply a fixed discount amount
* **Tax**: Configure tax rate and type (see [Calculations](/docs/estimates/creating-estimates#calculations) section)

**Optional:**

* **Assign to Employee**: Link estimate to a specific employee for performance tracking.
* **Estimate Mode**: Switch between **PRODUCT** and **HOURLY** modes using the toggle in the tab header.

### Estimate Modes [#estimate-modes]

Choose between two billing modes:

| Mode        | Best For                                  | Line Items Display    |
| ----------- | ----------------------------------------- | --------------------- |
| **PRODUCT** | Physical/digital products, fixed services | Quantity × Unit Price |
| **HOURLY**  | Time-based work, consulting               | Hours × Hourly Rate   |

***

### 2. Customer (Required) [#2-customer-required]

Select a customer from your saved customers list. You must have at least one customer to create an estimate.

<DocImage src="https://storage.pinebill.app/public/docs/image/Create-Estimate-PineBill-03-19-2026_12_21_PM.png" alt="Customer Selection Tab" maxHeight="400px" className="w-full p-2" />

**- Option A: Select existing customer** - Click "Select Customer" and search or browse your list.

**- [Option B: Add new customer](/docs/customers/adding-customers)** - Click "Add New Customer", fill in name, email, phone, and address, then save.

***

### 3. Estimate Details [#3-estimate-details]

Configure estimate metadata:

* **Estimate Number**: Click "Generate" to auto-create a unique number. Default behavior can be configured in [Estimate Settings](/docs/estimates/estimate-settings).
* **Issue Date**: When the estimate is created (Required)
* **Valid Until**: Expiration date for the estimate (Optional). Sets how long the customer has to accept. Default validity period can be configured in [Estimate Settings](/docs/estimates/estimate-settings).
* **Currency**: Select from available currencies. Changing the currency will affect calculations and display of all estimate values.
* **Currency Format**: Choose how amounts are displayed: **Symbol** (`$1,234.50`), **Localized symbol** (`US$1,234.50`), **Currency code** (`USD 1,234.50`), **Currency name** (`1,234.50 US dollars`), or **Accounting** (`($1,234.50)` for negative values).
* **Terms of Payment**: Payment conditions (e.g., "Net 30", "50% upfront").
* **End Message**: Custom note at bottom of estimate.
* **Custom Data Fields**: Add unlimited label-value pairs (e.g., Project Reference, Quote ID).

<DocImage src="https://storage.pinebill.app/public/docs/image/Create-Estimate-PineBill-03-19-2026_12_22_PM.png" alt="Estimate Details Tab" maxHeight="400px" className="w-full p-2" />

<Callout type="info">
  Unlike invoices, estimates do not have a Payment Methods tab. Payment methods are only relevant
  once an estimate is converted to an invoice.
</Callout>

***

### 4. Company Information [#4-company-information]

Your company details are automatically filled from your organization settings:

* Company name, address, email, phone
* **Logo**: Only if uploaded in [Organization Settings](/docs/organization/organization-settings)
* **Signature/Stamp**: Add a default signature for all estimates

All these details can be configured in [Organization Settings](/docs/organization/organization-settings).

<DocImage src="https://storage.pinebill.app/public/docs/image/Create-Estimate-PineBill-03-19-2026_12_23_PM.png" alt="Company Information Tab" maxHeight="400px" className="w-full p-2" />

***

### 5. Creating the Estimate [#5-creating-the-estimate]

Once all required fields are filled:

1. Click "Create Estimate" button (top right)
2. PDF is automatically generated
3. Estimate is saved with DRAFT status
4. You're redirected to the estimate detail page

From there you can:

* Download the PDF
* Share the estimate
* Send via email
* Update the status

***

## Calculations [#calculations]

### Tax Configuration [#tax-configuration]

Two tax types available:

* **Percentage (%)**: Tax calculated as percentage of subtotal
* **Fixed Amount**: Flat tax amount

**Tax Included Toggle:**

* **ON**: Prices already include tax (tax is extracted from total)
* **OFF**: Tax is added on top of prices (default)

### Calculation Formula [#calculation-formula]

```
Subtotal = Sum of (Quantity × Unit Price)
After Discount = Subtotal - Discount
Tax Amount = After Discount × (Tax Rate / 100)  [or Fixed Amount]
Grand Total = After Discount + Tax + Shipping
```

***

## Related Topics [#related-topics]

* [Estimate Details](/docs/estimates/estimate-details) - View and manage estimate information
* [Estimate Statuses](/docs/estimates/estimate-statuses) - Manage estimate lifecycle
* [Converting to Invoice](/docs/estimates/converting-to-invoice) - Turn estimates into invoices
* [Estimate Settings](/docs/estimates/estimate-settings) - Configure defaults and number generation


# Estimate Details Page (/docs/estimates/estimate-details)





## Overview [#overview]

The Estimate Details page displays all information about a specific estimate. Access it by clicking any estimate from the estimates list. The page is divided into two main sections: the left column contains estimate details, items, and customer information, while the right sidebar shows the total amount, PDF actions, and timeline.

<DocImage src="https://storage.pinebill.app/public/docs/image/Estimate-Details-PineBill-03-19-2026_12_27_PM.png" alt="Estimate Details Page Overview" maxHeight="500px" className="w-full p-2" />

***

## Page Header [#page-header]

At the top of the page, you'll find the estimate number and quick action buttons:

* **Back Button** - Returns you to the estimates list
* **Edit** - Open the estimate in the generator for full editing
* **[Share PDF](/docs/estimates/estimate-sharing)** - Create a new shareable link with customizable expiration
* **[Manage Shares](/docs/estimates/estimate-sharing)** - View and manage all shared links for this estimate
* **[Send via Email](/docs/estimates/estimate-sharing#sending-estimates-via-email)** - Send the estimate directly to the customer's email
* **Delete** - Permanently delete the estimate (owners only)
* **[Convert to Invoice](/docs/estimates/converting-to-invoice)** - Convert an accepted estimate into an invoice

<DocImage src="https://storage.pinebill.app/public/docs/image/Estimate-Details-PineBill-03-19-2026_12_29_PM.png" alt="Estimate Details Page Header" maxHeight="500px" className="w-full p-2" />

***

## Estimate Details [#estimate-details]

The estimate details section shows core information about your estimate. Some fields are editable directly from this page using quick inline edits. For comprehensive changes (items, customer, etc.), use the **Edit** button in the header to open the full estimate generator.

### Editable Fields [#editable-fields]

| Field           | How to Edit                                 | Notes                                                                        |
| --------------- | ------------------------------------------- | ---------------------------------------------------------------------------- |
| **Status**      | Click the status badge to open popover menu | Changes saved immediately. Options: Draft, Sent, Accepted, Declined, Expired |
| **Description** | Click edit icon to open text editor         | Add or modify estimate notes. Save or cancel changes                         |

### Read-Only Information [#read-only-information]

* **Estimate Number** - Unique identifier generated when the estimate was created
* **Issued Date** - When the estimate was originally created
* **Valid Until** - Expiration date for the estimate (how long the customer has to respond)
* **Exchange Rate** - Shows currency conversion rate for non-USD estimates

***

## Estimate Summary [#estimate-summary]

This section displays all line items and the calculation breakdown.

### Items List [#items-list]

Each item shows:

* Product or service name
* Model or SKU (if applicable)
* Unit price
* Quantity
* Line total (price × quantity)

### Calculations [#calculations]

Below the items table, you'll see the complete calculation:

1. **Subtotal** - Sum of all line items
2. **Shipping** - Delivery or shipping costs (if applicable)
3. **Discount** - Applied discount amount (displayed in green)
4. **Tax** - Tax amount with rate shown as percentage or fixed amount
   * Tax included estimates show "(included)" next to the tax rate
5. **Total** - Final estimated amount

***

## Customer Information [#customer-information]

View complete customer details including:

* Full name
* Email address
* Phone number
* Complete billing address with zip code

This information is pulled from the customer record and cannot be edited directly from the estimate. To update customer details, go to the [Editing Customers](/docs/customers/editing-customer) section.

***

## Assigned Employee [#assigned-employee]

Track which team member is responsible for this estimate.

### When No Employee is Assigned [#when-no-employee-is-assigned]

You'll see a placeholder with an "Assign Employee" button. Click it to open the employee selector and choose from your team members.

### When Employee is Assigned [#when-employee-is-assigned]

The card displays:

* Employee name
* Employee ID
* Email and phone (if available)
* Position and department (if specified)

You can **Change** the assigned employee or **Unassign** to remove the employee from this estimate.

***

## Custom Fields [#custom-fields]

If the estimate includes custom fields, they appear in the "Additional Information" section. These are custom label-value pairs you added when creating the estimate, such as:

* Project Reference
* Quote ID
* Department Code
* Any other custom data

***

## Terms & Notes [#terms--notes]

This section displays:

* **Terms of Payment** - Payment conditions and deadlines
* **Additional Notes** - Custom end message or notes included on the estimate

***

## Right Sidebar [#right-sidebar]

### Total Amount [#total-amount]

The total amount is prominently displayed at the top of the sidebar, showing:

* Primary amount in the estimate currency
* Converted amount (if currency is not USD)
* Currency code

### PDF Document [#pdf-document]

Click **View PDF** to open the estimate PDF in a viewer modal where you can:

* Preview the PDF
* Download the PDF to your device
* Print the estimate

<DocImage src="https://storage.pinebill.app/public/docs/image/Estimate-Details-PineBill-03-19-2026_12_32_PM.png" alt="Estimate PDF Viewer Modal" maxHeight="500px" className="w-full p-2" />

### Timeline [#timeline]

The timeline tracks important dates and events:

* **Created** - When the estimate was first generated, with precise timestamp
* **Last Updated** - Most recent modification date and time

Each event includes both date and time for complete tracking.

***

## Email History [#email-history]

If you've sent the estimate via email, the Email History section shows all sent emails with details including:

* Recipient email address
* When it was sent
* Who sent it
* Click tracking statistics (how many times the "View Estimate" link was clicked)

***

## Related Topics [#related-topics]

* [Creating Estimates](/docs/estimates/creating-estimates) - Step-by-step guide to creating estimates
* [Estimate Statuses](/docs/estimates/estimate-statuses) - Understanding the estimate lifecycle
* [Estimate Sharing](/docs/estimates/estimate-sharing) - Send and share estimates securely
* [Converting to Invoice](/docs/estimates/converting-to-invoice) - Turn estimates into invoices
* [Estimate List](/docs/estimates/estimate-list) - Managing multiple estimates


# Estimates List (/docs/estimates/estimate-list)





## Estimates List and Filtering [#estimates-list-and-filtering]

Access all your estimates from the Estimates page with powerful search and filtering capabilities.

## List View Features [#list-view-features]

### Table Columns [#table-columns]

| Column        | Description                                       |
| ------------- | ------------------------------------------------- |
| Checkbox      | Select estimate for bulk actions (owners only)    |
| Estimate #    | Unique estimate identifier                        |
| Customer Name | Name of the customer                              |
| Amount        | Total amount with currency                        |
| Status        | Current status (color-coded pill)                 |
| Issue Date    | When estimate was created                         |
| Valid Until   | Expiration date for the estimate                  |
| Assigned To   | Employee assignment (if applicable)               |
| Actions       | Quick actions (view, edit, change status, delete) |

### Sorting Options [#sorting-options]

| Feature        | Description                         |
| -------------- | ----------------------------------- |
| Column Sort    | Click any column header to sort     |
| Sort Direction | Toggle between ascending/descending |
| Default Sort   | Newest first (by creation date)     |

### Pagination Controls [#pagination-controls]

| Option         | Description                           |
| -------------- | ------------------------------------- |
| Items per Page | 10, 25, 50, or 100 estimates per page |
| Navigation     | Previous/Next buttons                 |
| Page Jump      | Jump to specific page number          |

<DocImage src="https://storage.pinebill.app/public/docs/image/Estimates-PineBill-03-19-2026_12_40_PM.png" alt="Estimates List View" maxHeight="440px" className="w-full p-0" />

## Search and Filtering [#search-and-filtering]

Find estimates quickly with powerful filters:

### Search Bar [#search-bar]

| Search Type      | Description                      |
| ---------------- | -------------------------------- |
| Estimate Number  | Search by unique estimate ID     |
| Customer Name    | Search by customer name          |
| Customer Email   | Search by customer email address |
| Description      | Search in estimate description   |
| Real-time Search | Results update as you type       |

### Status Filter [#status-filter]

| Feature            | Options                                             |
| ------------------ | --------------------------------------------------- |
| Available Statuses | Draft, Sent, Accepted, Declined, Expired, Converted |
| Selection Type     | Multi-select to show multiple statuses              |
| Filter Display     | Active filters shown as removable chips             |

### Date Range Filter [#date-range-filter]

| Filter Type   | Options                                            |
| ------------- | -------------------------------------------------- |
| Range Type    | Filter by issued date range                        |
| Quick Presets | Last 7 days, Last 30 days, Last 90 days, This Year |
| Custom Range  | Custom date range picker                           |

### Active Filters Management [#active-filters-management]

| Feature       | Description                    |
| ------------- | ------------------------------ |
| Display       | Shown as chips above the table |
| Remove Filter | Click X on any chip to remove  |
| Clear All     | Reset all filters at once      |

<DocImage src="https://storage.pinebill.app/public/docs/image/Estimates-PineBill-03-19-2026_12_41_PM.png" alt="Estimates List Filters" maxHeight="440px" className="w-full p-0" />

## Bulk Actions [#bulk-actions]

Select multiple estimates to perform batch operations, saving time when managing large numbers of estimates.

### Selecting Estimates [#selecting-estimates]

| Feature             | Description                                                             |
| ------------------- | ----------------------------------------------------------------------- |
| Checkbox Column     | Click the checkbox next to any estimate to select it                    |
| Select All          | Use the header checkbox to select all estimates on the current page     |
| Indeterminate State | Header checkbox shows a minus icon when some (but not all) are selected |
| Selection Count     | Shows how many estimates are currently selected                         |

### Available Bulk Actions [#available-bulk-actions]

When you have estimates selected, a bulk actions bar appears with the following options:

| Action          | Description                                         |
| --------------- | --------------------------------------------------- |
| Change Status   | Update the status of all selected estimates at once |
| Delete Selected | Remove all selected estimates (with confirmation)   |
| Clear Selection | Deselect all estimates                              |

### Bulk Status Change [#bulk-status-change]

Change the status of multiple estimates simultaneously:

1. Select the estimates you want to update
2. Click **Change Status** in the bulk actions bar
3. Choose the new status from the dropdown
4. Confirm the change in the dialog

<Callout type="info">
  Estimates with CONVERTED status cannot be changed via bulk status update.
</Callout>

### Bulk Delete [#bulk-delete]

Remove multiple estimates at once:

1. Select the estimates you want to delete
2. Click **Delete Selected**
3. Review the confirmation dialog showing the number of estimates to be deleted
4. Confirm to permanently remove the selected estimates

<Callout type="warning">
  Bulk delete is permanent and cannot be undone. All associated data including PDFs will be removed.
</Callout>

<Callout type="note">
  Bulk actions are only available to organization owners.
</Callout>

## Tips for Efficient Search [#tips-for-efficient-search]

<Callout type="tip">
  Use the search bar for quick lookups by customer or estimate number. Combine multiple filters to
  narrow down results when managing large estimate lists.
</Callout>

* Combine multiple filters for precise results
* Use status filters to focus on actionable estimates (e.g., Accepted, ready for conversion)
* Save time with date presets for common reports
* Use bulk actions to update multiple estimates at once
* Clear all filters to start fresh


# Estimate Settings (/docs/estimates/estimate-settings)







## Overview [#overview]

Estimate Settings let you control how estimate numbers are generated, set the default validity period, and configure default content for new estimates. This saves time and ensures consistency across all your estimates.

<Callout type="info">
  Only organization owners can edit estimate settings.
</Callout>

## Accessing Estimate Settings [#accessing-estimate-settings]

Open estimate settings from the centralized settings hub:

1. Open &#x2A;*[Settings](/dashboard/setup)**
2. In **Documents*&#x2A;, click &#x2A;*[Estimate Settings](/dashboard/estimates/settings)**
3. Click the **Edit Settings** button (owners only)

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-04-15-2026_04_39_PM.png" alt="Estimate Settings Page Overview" maxHeight="500px" className="w-[95%] p-2" />

***

## Estimate Number Generation [#estimate-number-generation]

Control how estimate numbers are automatically created for each new estimate.

### Generation Strategy [#generation-strategy]

Choose how your estimate numbers will be formatted:

| Strategy          | Description                         | Example                                  | Best For                                                              |
| ----------------- | ----------------------------------- | ---------------------------------------- | --------------------------------------------------------------------- |
| **Sequential**    | Creates numbered estimates in order | `EST-2025-0001`, `EST-2025-0002`         | Small businesses, simple numbering, easy customer reference           |
| **Secure Random** | Generates random alphanumeric codes | `EST-2025-A7K9M2`, `EST-2025-X3F8P1`     | Enhanced security, preventing number guessing, high-volume businesses |
| **Timestamp**     | Uses date and time                  | `EST-20250910-X4Y7`, `EST-20250910-P9K2` | Date-based organization, chronological sorting, time tracking         |

### Prefix [#prefix]

Set the prefix that appears at the start of all estimate numbers.

**Requirements:**

* 3-10 characters
* Default: `EST`
* Examples: `EST`, `QUO`, `PROP`

### Sequence Length [#sequence-length]

Control how many digits appear in sequential numbers.

**Settings:**

* Minimum: 4 digits
* Maximum: 10 digits
* Example: Length 4 = `0001`, Length 6 = `000001`

<Callout type="tip">
  Use longer sequences if you create many estimates per year.
</Callout>

<Callout type="warning">
  Changing estimate number settings doesn't affect existing estimates, only new ones.
</Callout>

***

## Default Validity Period [#default-validity-period]

Set how many days an estimate remains valid after creation. This automatically calculates the "Valid Until" date when creating new estimates.

| Setting      | Details                                  |
| ------------ | ---------------------------------------- |
| **Range**    | 1 to 365 days                            |
| **Default**  | 30 days                                  |
| **Behavior** | Sets "Valid Until" = Issue Date + N days |

<Callout type="tip">
  Choose a validity period that gives customers enough time to respond while keeping your pricing
  commitments manageable. 30 days is standard for most businesses.
</Callout>

***

## Saving Your Settings [#saving-your-settings]

After making changes:

1. Review all your settings
2. Check the estimate number preview
3. Click **Save Estimate Settings**
4. Wait for the success message

<Callout type="tip">
  Click 

  **Cancel**

   to discard changes and restore previous settings.
</Callout>

***

## Troubleshooting [#troubleshooting]

<Accordions type="single">
  <Accordion title="Can't edit settings" id="cant-edit-settings">
    Only organization owners can edit estimate settings. Contact your organization owner to make changes or request ownership transfer.
  </Accordion>

  <Accordion title="Preview not updating" id="preview-not-updating">
    Make sure you've selected a generation strategy. The preview updates automatically when you change
    prefix, length, or pattern fields.
  </Accordion>

  <Accordion title="Settings not saving" id="settings-not-saving">
    Ensure all required fields are filled correctly. Check that prefix is 3-10 characters and sequence
    length is 4-10 digits. Look for error messages.
  </Accordion>

  <Accordion title="Estimate numbers duplicating" id="duplicate-numbers">
    Contact support if you see duplicate estimate numbers. This shouldn't happen
    with any generation strategy.
  </Accordion>
</Accordions>


# Estimate Sharing (/docs/estimates/estimate-sharing)







## How To Share Your Estimates [#how-to-share-your-estimates]

Share your estimates with clients, vendors, or team members using secure links or email. You can create multiple share links for each estimate with different settings, or send estimates directly via email with PDF attachments.

## Sending Estimates via Email [#sending-estimates-via-email]

Send your estimates directly to customers via email with professional templates and PDF attachments.

### How to Send an Estimate by Email [#how-to-send-an-estimate-by-email]

<DocImage src="https://storage.pinebill.app/public/docs/image/Estimate-Details-PineBill-03-19-2026_12_35_PM.png" alt="Estimate Email Dialog" maxHeight="350px" className="w-full p-0" />

1. Open the estimate you want to send
2. Click the **Send via Email** button at the top right
3. Enter recipient email addresses (up to 5 recipients)
4. Add a custom message (optional, up to 500 characters)
5. Click **Send Email**

### What Your Customer Receives [#what-your-customer-receives]

When you send an estimate via email, your customer gets:

* **Professional email** with your company name and estimate details
* **PDF attachment** of the complete estimate
* **Secure link** to view the estimate online
* **Your custom message** (if you added one)
* Estimate number, amount, and validity date clearly displayed

### Email Tracking [#email-tracking]

Track engagement with your sent estimates:

* See when emails were sent and by whom
* Track how many times the "View Estimate" link was clicked
* View the last time the link was accessed
* Monitor all email activity in the Email History section
* Receive notifications when customers accept or deny the estimate

### Email History [#email-history]

View the complete email history for each estimate:

<DocImage src="https://storage.pinebill.app/public/docs/image/Estimate-Details-PineBill-03-19-2026_12_37_PM.png" alt="Estimate Email History" maxHeight="350px" className="w-full p-2" />

1. Open your estimate
2. Scroll to the **Email History** section
3. See all sent emails with details including:
   * Recipient email address
   * When it was sent
   * Who sent it
   * Click tracking statistics

## Sharing via Secure Links [#sharing-via-secure-links]

Create shareable links for your estimates with customizable security options.

## How to Share an Estimate [#how-to-share-an-estimate]

1. Open the estimate you want to share
2. Click the **Share PDF** button at the top right
3. Choose your security settings
4. Click **Create Share Link**
5. Copy and share the link

<DocImage src="https://storage.pinebill.app/public/docs/image/Estimate-Details-PineBill-03-19-2026_12_38_PM.png" alt="Estimate Share Dialog" maxHeight="500px" className="w-full p-0" />

## Customer Approval Responses [#customer-approval-responses]

Customers can respond directly from the shared estimate page after opening the
secure link. They can accept or deny the estimate and add an optional note for
context.

### What Customers Can Do [#what-customers-can-do]

* **Accept** the estimate when they approve the pricing and terms
* **Deny** the estimate when they do not want to proceed
* **Add a note** to explain their decision or provide next steps
* **Download the PDF** if they have access to the share

<DocImage src="https://storage.pinebill.app/public/changelogs/images/Estimate-EST-2026-AI2PMDL0-Donald-A-Mosley-PineBill-05-03-2026_12_35_PM.png" alt="Improved Analytics Dashboard" className="w-full px-2" />

### What Your Team Sees [#what-your-team-sees]

When a customer submits a response:

* The estimate status changes to **Accepted** or **Declined**
* Organization members receive an email and dashboard notification
* The estimate detail page shows the response, timestamp, and customer note
* Accepted estimates can be converted into invoices from the estimate detail page

<DocImage src="https://storage.pinebill.app/public/changelogs/images/Estimate-Details-PineBill-05-03-2026_12_40_PM.png" alt="Improved Analytics Dashboard" className="w-full px-2" />

## Security Options [#security-options]

### Password Protection [#password-protection]

Add a password to protect your estimate from unauthorized access.

**How to use:**

1. Check the **Password Protection** box
2. Enter a password (at least 4 characters)
3. Click the eye icon to show/hide your password
4. Share the password separately from the link (by phone, text, or separate email)

### Expiration Date [#expiration-date]

Make your share link expire automatically after a certain time.

**Quick options:**

* **1 hour** - For immediate review
* **1 day** - Short-term access
* **1 week** - Standard estimate delivery

<Callout type="warning">
  If you don't set an expiration, the link will work forever and it will be a public link. You'll
  see a yellow warning when creating a permanent link. Once you created a permanent link, you cannot
  add expiring links to the same estimate later.
</Callout>

### View Limit [#view-limit]

Limit how many times people can view your estimate.

**When to use:**

* Controlling who can access the estimate
* Tracking how many times it's been viewed
* Preventing unlimited sharing

**How to use:**

1. Check the **Limit Views** box
2. Enter the maximum number of views (1 to 10,000)
3. The link stops working once it reaches this limit

***

## Managing Your Shares [#managing-your-shares]

View and manage all your share links in one place.

### View All Shares [#view-all-shares]

1. Open your estimate
2. Click the **Manage Shares** button at the top right
3. See all your active and inactive shares

### Understanding Share Status [#understanding-share-status]

Each share shows its current status:

* **Active** - Link is working
* **Expired** - Past the expiration date
* **View Limit Reached** - Maximum views used up
* **Revoked** - Manually disabled

You'll also see:

* **Public** badge - No expiration (permanent link)
* **Protected** badge - Password required

### What You Can See [#what-you-can-see]

For each share link:

* Who created it and when
* Expiration date (or "Never")
* How many times it's been viewed
* When it was last viewed
* The share URL (for active links)

### Copy a Share Link [#copy-a-share-link]

1. Find the share you want to copy
2. Click the copy icon next to the URL
3. You'll see a confirmation message
4. Paste and share the link

### Delete a Share Link [#delete-a-share-link]

Organization owners can delete any share link:

1. Click the **Manage Shares** button
2. Find the share you want to delete
3. Click the trash icon
4. Confirm deletion

<Callout type="warning">
  Once deleted, the link stops working immediately and can't be restored.
</Callout>

## Quick Reference [#quick-reference]

### Email Features [#email-features]

| Feature         | What it does                       | Limit                |
| --------------- | ---------------------------------- | -------------------- |
| Recipients      | Send to multiple email addresses   | Up to 5 per send     |
| Custom Message  | Personal message in email          | 500 characters       |
| PDF Attachment  | Estimate PDF attached to email     | Included             |
| Email Tracking  | Track link clicks and engagement   | Unlimited tracking   |
| Email History   | View all sent emails for estimate  | Complete history     |
| Response Alerts | Notify team when customer responds | Organization members |

### Secure Link Features [#secure-link-features]

| Feature             | What it does                   | Maximum              |
| ------------------- | ------------------------------ | -------------------- |
| Password            | Requires password to view      | 4 characters minimum |
| Expiration          | Link stops working after date  | 7 days from now      |
| View Limit          | Maximum number of views        | 10,000 views         |
| Shares per Estimate | How many links you can create  | Unlimited            |
| Customer Response   | Accept or deny from share page | One response         |

## Troubleshooting [#troubleshooting]

<Accordions type="single">
  <Accordion title="Email not sending" id="email-not-sending">
    **Common causes:**

    * Missing customer email address - update customer information
    * Invalid email format - check the email address is correct
    * Estimate PDF not generated - regenerate the estimate

    If the problem persists, check your SMTP configuration.
  </Accordion>

  <Accordion title="Customer didn't receive the email" id="email-not-received">
    **Steps to resolve:** 1. Check the Email History to confirm it was sent 2. Ask the customer to
    check their spam/junk folder 3. Verify the email address is correct 4. Resend the email or create
    a secure link as an alternative
  </Accordion>

  <Accordion title="This link has expired" id="link-expired">
    The link passed its expiration date. Create a new share link or resend the estimate via email.
  </Accordion>

  <Accordion title="View limit has reached" id="view-limit-reached">
    Too many people viewed it. Create a new link with a higher limit or no limit.
  </Accordion>

  <Accordion title="Where can I see a customer's response?" id="customer-response-location">
    Open the estimate detail page in your dashboard. If the customer has accepted or denied the
    estimate, you'll see a Customer Response section with the decision, response time, and any note
    they submitted.
  </Accordion>

  <Accordion title="Can't access password-protected link" id="cant-access-password">
    Make sure you have both the link AND the password. Check that you entered the password correctly (it's case-sensitive).
  </Accordion>
</Accordions>

<Callout type="info">
  Only organization owners can delete share links. Emails can be sent by any team member with access
  to the estimate.
</Callout>


# Estimate Statuses (/docs/estimates/estimate-statuses)





## Status Overview [#status-overview]

PineBill uses six distinct status codes to track the estimate lifecycle:

| Status           | Purpose                          | When to Use                                                                          |
| ---------------- | -------------------------------- | ------------------------------------------------------------------------------------ |
| ⚪ **DRAFT**      | Estimate is being prepared       | Creating new estimate<br />Making edits before sending<br />Incomplete estimate data |
| 🔵 **SENT**      | Estimate sent, awaiting response | Estimate delivered to customer<br />Waiting for acceptance or decline                |
| 🟢 **ACCEPTED**  | Customer agreed to the estimate  | Customer confirmed the pricing and terms<br />Ready to convert to invoice            |
| 🔴 **DECLINED**  | Customer rejected the estimate   | Customer does not agree to terms<br />Pricing not accepted                           |
| 🟡 **EXPIRED**   | Past the valid-until date        | Validity period has passed<br />Customer did not respond in time                     |
| 🟣 **CONVERTED** | Converted into an invoice        | Estimate successfully turned into an invoice                                         |

## Status Transitions [#status-transitions]

Common status workflows:

**Standard flow:**

```
DRAFT → SENT → ACCEPTED → CONVERTED
```

**Declined flow:**

```
DRAFT → SENT → DECLINED
```

**Expired flow:**

```
DRAFT → SENT → EXPIRED
```

**Revised flow:**

```
SENT → DECLINED → (create new estimate with revised pricing)
```

## Manual vs Automatic [#manual-vs-automatic]

**Manual changes required:**

* All status transitions must be manually updated (except CONVERTED)
* No automatic SENT → EXPIRED transition — you must update this manually

**Automatic behavior:**

* CONVERTED status is set automatically when you convert an estimate to an invoice
* Once CONVERTED, the status is locked and cannot be changed

## Changing Status [#changing-status]

### Single Estimate [#single-estimate]

You can change the status of a single estimate in two ways:

1. **From the estimate list:** Click on the status badge to open the status selector
2. **From estimate details:** Click the status badge in the estimate details page

### Bulk Status Change [#bulk-status-change]

Update multiple estimates at once:

1. Select estimates using the checkboxes in the estimate list
2. Click **Change Status** in the bulk actions bar
3. Choose the new status
4. Confirm the change

<Callout type="tip">
  Bulk status change is useful for marking multiple expired estimates at once, or updating sent
  estimates to reflect customer responses.
</Callout>

## CONVERTED Status [#converted-status]

The CONVERTED status is special:

* It is set automatically when you [convert an estimate to an invoice](/docs/estimates/converting-to-invoice)
* Once converted, the estimate is **locked** — you cannot change the status back
* The estimate details page shows a link to the created invoice
* This ensures a clear audit trail from estimate to invoice

<Callout type="info">
  Only estimates with ACCEPTED status can be converted to invoices. Make sure to update the status
  before attempting conversion.
</Callout>


# Estimate Management (/docs/estimates)







## Estimate Management Overview [#estimate-management-overview]

Estimates (also known as quotes or proposals) let you present pricing to customers before committing to an invoice. Use estimates to agree on scope, pricing, and terms — then convert accepted estimates directly into invoices with one click.

## Estimate Lifecycle [#estimate-lifecycle]

Understanding how estimates flow through your business:

```
Draft → Sent → Accepted → Converted (to Invoice)
              ↓
           Declined
```

Any status can also be affected by:

```
→ Expired (if past validity date)
```

**Status Meanings:**

| Status        | Description                                | Next Actions                         |
| ------------- | ------------------------------------------ | ------------------------------------ |
| **Draft**     | Created but not sent to customer           | Edit, send, or delete                |
| **Sent**      | Shared with customer, awaiting response    | Follow up, mark accepted or declined |
| **Accepted**  | Customer agreed to the estimate            | Convert to invoice                   |
| **Declined**  | Customer rejected the estimate             | Revise and resend, or archive        |
| **Expired**   | Past the valid-until date without response | Create new estimate or extend        |
| **Converted** | Successfully converted into an invoice     | View linked invoice                  |

Learn more about [Estimate Statuses](/docs/estimates/estimate-statuses).

## Key Features [#key-features]

Explore powerful estimate management features:

<Cards>
  <Card title="Creating Estimates" description="Step-by-step guide to building professional estimates" href="/docs/estimates/creating-estimates" />

  <Card title="Estimate Details" description="View and manage all information about a specific estimate" href="/docs/estimates/estimate-details" />

  <Card title="Estimate Statuses" description="Track your estimates through their lifecycle" href="/docs/estimates/estimate-statuses" />

  <Card title="Sharing Estimates" description="Send estimates via email or secure share links" href="/docs/estimates/estimate-sharing" />

  <Card title="Estimate List" description="Search, sort, and filter your estimates efficiently" href="/docs/estimates/estimate-list" />

  <Card title="Converting to Invoice" description="Turn accepted estimates into invoices with one click" href="/docs/estimates/converting-to-invoice" />

  <Card title="Estimate Settings" description="Configure estimate numbers, defaults, and preferences" href="/docs/estimates/estimate-settings" />
</Cards>

## Estimate List and Filtering [#estimate-list-and-filtering]

Access and manage all your estimates with powerful search, sorting, and filtering capabilities. Find exactly what you need with status filters, date ranges, and text search.

[Learn more about Estimate List and Filtering →](/docs/estimates/estimate-list)

## Converting Estimates to Invoices [#converting-estimates-to-invoices]

One of PineBill's most powerful features — convert an accepted estimate directly into an invoice. All items, pricing, customer details, and terms are carried over automatically.

[Learn more about Converting to Invoice →](/docs/estimates/converting-to-invoice)

## Troubleshooting [#troubleshooting]

<Accordions type="single">
  <Accordion title="Can't Create Estimate" id="cant-create-estimate">
    **Problem:** Estimate generator not working.

    **Solutions:**

    * Ensure you've completed organization setup
    * Check you have at least one customer
    * Verify you have products or can add temporary items
    * Clear browser cache and try again
  </Accordion>

  <Accordion title="Estimate Number Conflicts" id="estimate-number-conflicts">
    **Problem:** Duplicate estimate numbers.

    **Solutions:**

    * Check estimate number settings
    * Switch to SECURE\_RANDOM strategy to avoid conflicts
    * Contact support if issue persists
  </Accordion>

  <Accordion title="PDF Won't Generate" id="pdf-wont-generate">
    **Problem:** Error when generating estimate PDF.

    **Solutions:**

    * Verify all required fields are filled
    * Check that customer has a name
    * Ensure at least one line item exists
    * Try a different template
    * Contact support with error message
  </Accordion>
</Accordions>


# Creating Expenses (/docs/expenses/creating-expenses)







## Quick Start [#quick-start]

Go to &#x2A;*[Dashboard](/dashboard)*&#x2A; -> &#x2A;*[Expenses](/dashboard/expenses)** and click **Add Expense**.

<DocImage src="https://storage.pinebill.app/public/docs/image/Expenses-PineBill-04-27-2026_10_03_PM.png" alt="Add expense dialog" maxHeight="500px" className="w-full p-0" />

***

## Expense Fields [#expense-fields]

| Field              | Required | Notes                                                                                      |
| ------------------ | -------- | ------------------------------------------------------------------------------------------ |
| **Title**          | Yes      | Short name for the expense, such as "Client lunch" or "Figma subscription"                 |
| **Amount**         | Yes      | Must be greater than zero                                                                  |
| **Currency**       | Yes      | Defaults to USD, but you can choose another currency                                       |
| **Date**           | Yes      | Defaults to today                                                                          |
| **Category**       | Yes      | Software, Office, Travel, Meals, Marketing, Equipment, Contractors, Taxes / Fees, or Other |
| **Vendor**         | No       | Merchant, supplier, or service provider                                                    |
| **Payment Method** | No       | Card, cash, bank transfer, or another method                                               |
| **Customer**       | No       | Link the expense to a customer                                                             |
| **Invoice**        | No       | Link the expense to an existing invoice                                                    |
| **Receipt**        | No       | Upload one image or PDF receipt                                                            |
| **Notes**          | No       | Internal context, tax notes, or project details                                            |

Receipts can be **PNG, JPG, JPEG, WebP, GIF, or PDF** files up to **5MB**.

***

## Step-by-Step Guide [#step-by-step-guide]

<Steps>
  <Step>
    ### 1. Open the Expense Form [#1-open-the-expense-form]

    1. Go to &#x2A;*[Expenses](/dashboard/expenses)**
    2. Click **Add Expense**
    3. Enter a title, amount, currency, date, and category
  </Step>

  <Step>
    ### 2. Add Optional Details [#2-add-optional-details]

    Open **More details** to add:

    * Vendor
    * Payment method
    * Customer
    * Invoice
    * Receipt
    * Notes

    If you select a customer first, the invoice picker only shows invoices for that customer. If you select an invoice first, PineBill fills the matching customer when one exists.
  </Step>

  <Step>
    ### 3. Attach a Receipt [#3-attach-a-receipt]

    Drag a receipt into the upload area or choose a file from your device.

    <DocImage src="https://storage.pinebill.app/public/docs/image/Expenses-PineBill-04-28-2026_09_36_AM.png" alt="Receipt upload area" maxHeight="400px" className="w-full p-0" />
  </Step>

  <Step>
    ### 4. Save [#4-save]

    Click **Save Expense**. The expense appears in the list and is included in totals, filters, export, and analytics.
  </Step>
</Steps>

***

## After Saving [#after-saving]

Once an expense is saved, you can:

* Open it from the Expenses list
* Edit details or notes
* View, replace, or delete the receipt
* Link it to a customer or invoice
* Convert it to an invoice draft
* Include it in CSV exports and analytics

***

## Related Topics [#related-topics]

* [Expense Management](/docs/expenses) - Manage and review expenses
* [Extract from Receipt](/docs/expenses/extract-from-receipt) - Scan receipts with AI
* [Creating Invoices](/docs/invoices/creating-invoices) - Finish invoice drafts from expenses
* [Customers](/docs/customers/adding-customers) - Add customers before linking expenses


# Extract from Receipt (/docs/expenses/extract-from-receipt)







## Quick Start [#quick-start]

Go to &#x2A;*[Dashboard](/dashboard)*&#x2A; -> &#x2A;*[Expenses](/dashboard/expenses)** and click **Extract from Receipt**.

<DocImage src="https://storage.pinebill.app/public/docs/image/Expenses-PineBill-05-21-2026_09_32_PM.png" alt="Extract from Receipt button on Expenses page" maxHeight="500px" className="w-full p-2" />

PineBill uses AI to read your receipt and automatically fill in the expense form with the extracted details — title, amount, currency, date, category, vendor, and payment method.

<Callout type="info">
  Extract from Receipt uses AI credits. Each scan costs **2.5 credits**. You can check your credit
  balance in the [AI Credits](/docs/subscription/ai-credits) settings.
</Callout>

***

## How It Works [#how-it-works]

Extract from Receipt uses an AI vision model to read uploaded receipt images and PDFs. The model identifies expense-relevant information in the document and returns structured data that PineBill uses to pre-fill the expense form.

The AI extracts:

| Field              | Description                                                        |
| ------------------ | ------------------------------------------------------------------ |
| **Title**          | A short name derived from the receipt or vendor name               |
| **Amount**         | The final total paid or payable                                    |
| **Currency**       | ISO 4217 currency code detected from the document                  |
| **Date**           | Transaction date in the receipt                                    |
| **Category**       | Automatically classified into one of PineBill's expense categories |
| **Vendor**         | Merchant or service provider name                                  |
| **Payment Method** | Card, cash, bank transfer, or other method if visible              |
| **Notes**          | Additional context found in the document                           |

The AI also extracts line items, tax details, and totals from the receipt for your review.

***

## Supported File Types [#supported-file-types]

| Format     | Extensions                |
| ---------- | ------------------------- |
| **Images** | PNG, JPG, JPEG, WebP, GIF |
| **PDF**    | PDF                       |

Maximum file size: **5MB**.

***

## Step-by-Step Guide [#step-by-step-guide]

<Steps>
  <Step>
    ### 1. Open Extract from Receipt [#1-open-extract-from-receipt]

    Go to &#x2A;*[Expenses](/dashboard/expenses)** and click **Extract from Receipt**. A dialog opens with a drag-and-drop upload area.

    <DocImage src="https://storage.pinebill.app/public/docs/image/Expenses-PineBill-05-21-2026_09_35_PM.png" alt="Extract from Receipt upload dialog" maxHeight="400px" className="w-full p-2" />
  </Step>

  <Step>
    ### 2. Upload Your Receipt [#2-upload-your-receipt]

    Drag a receipt file into the upload area, or click to browse your device. PineBill shows a preview of the uploaded file.

    <DocImage src="https://storage.pinebill.app/public/docs/image/Expenses-PineBill-05-21-2026_09_36_PM.png" alt="Receipt file preview before scanning" maxHeight="400px" className="w-full p-2" />

    You can remove the file and choose a different one before scanning.
  </Step>

  <Step>
    ### 3. Scan the Receipt [#3-scan-the-receipt]

    Click **Scan receipt** to start the AI extraction. The dialog shows a scanning animation while the AI reads your document. This usually takes a few seconds.

    <DocImage src="https://storage.pinebill.app/public/docs/image/Expenses-PineBill-05-21-2026_09_37_PM.png" alt="Receipt scanning in progress" maxHeight="400px" className="w-full p-2" />

    The credit cost is displayed before you confirm the scan. If you don't have enough credits, the scan button is disabled.
  </Step>

  <Step>
    ### 4. Review Extracted Details [#4-review-extracted-details]

    After a successful scan, PineBill opens the Add Expense form pre-filled with the extracted data. You can review and adjust any field before saving.

    The form shows an extraction review with:

    * **Document type** — what kind of document was detected (receipt, bill, purchase invoice, etc.)
    * **Confidence scores** — how confident the AI is about each extracted field
    * **Warnings** — any issues found during extraction, such as missing amounts or unclear text
  </Step>

  <Step>
    ### 5. Save the Expense [#5-save-the-expense]

    Review the pre-filled fields, make any corrections, and click **Save Expense**. The uploaded receipt is automatically attached to the expense.

    <DocImage src="https://storage.pinebill.app/public/docs/image/Expenses-PineBill-05-21-2026_09_38_PM.png" alt="Successful receipt scan result" maxHeight="400px" className="w-full p-2" />
  </Step>
</Steps>

***

## Category Detection [#category-detection]

The AI automatically classifies expenses into one of PineBill's categories based on the content of the receipt:

| Category         | Examples                                             |
| ---------------- | ---------------------------------------------------- |
| **Software**     | SaaS subscriptions, hosting, domains, APIs, licenses |
| **Office**       | Office supplies, stationery, coworking, rent         |
| **Travel**       | Flights, hotels, taxis, trains, fuel, parking        |
| **Meals**        | Restaurants, cafes, food, coffee, catering           |
| **Marketing**    | Ads, campaigns, design, branding, promotion          |
| **Equipment**    | Computers, phones, hardware, tools, furniture        |
| **Contractors**  | Freelancers, agencies, consultants                   |
| **Taxes / Fees** | Taxes, government fees, bank fees, accounting fees   |
| **Other**        | Anything that doesn't fit the above categories       |

You can change the category after extraction if the AI classification doesn't match.

***

## AI Credits [#ai-credits]

Each receipt scan costs **2.5 AI credits**. Credits are deducted after the scan completes successfully. If the scan fails, no credits are charged.

## Tips for Best Results [#tips-for-best-results]

* Use clear, well-lit photos or high-resolution scans
* Make sure the entire receipt is visible in the image
* Avoid blurry, folded, or partially cropped receipts
* PDF receipts from digital purchases typically give the best results
* If extraction fails, try a different photo angle or a higher quality scan

## Common Questions [#common-questions]

<Accordions type="single">
  <Accordion title="What happens if the AI can't read my receipt?" id="unreadable-receipt">
    The scan will fail and you'll see an error message. No credits are charged for failed scans. Try uploading a clearer image or a different file format.
  </Accordion>

  <Accordion title="Can I edit the extracted details?" id="edit-extracted">
    Yes. After extraction, all fields are editable in the expense form. The AI pre-fills the form but
    you have full control before saving.
  </Accordion>

  <Accordion title="Is my receipt stored after scanning?" id="receipt-storage">
    The receipt file is attached to the expense when you save it. If you cancel without saving, the
    file is not stored.
  </Accordion>

  <Accordion title="Why does the category look wrong?" id="wrong-category">
    The AI classifies based on the receipt content. If the classification doesn't match, select the
    correct category in the expense form before saving.
  </Accordion>

  <Accordion title="What if I don't have enough credits?" id="not-enough-credits">
    The scan button is disabled when your credit balance is below the required amount. Purchase more credits in [AI Credits](/docs/subscription/ai-credits).
  </Accordion>
</Accordions>

***

## Related Topics [#related-topics]

* [Creating Expenses](/docs/expenses/creating-expenses) - Add expense records manually
* [Expense Management](/docs/expenses) - Manage and review expenses
* [AI Credits](/docs/subscription/ai-credits) - Check balance and purchase credits


# Expense Management (/docs/expenses)







## Quick Start [#quick-start]

Use Expenses to record business costs, keep receipts attached, connect costs to customers or invoices, and turn expenses into invoice line items when you need to bill them back.

Go to &#x2A;*[Dashboard](/dashboard)*&#x2A; -> &#x2A;*[Expenses](/dashboard/expenses)**.

<DocImage src="https://storage.pinebill.app/public/docs/image/Expenses-PineBill-04-27-2026_10_03_PM.png" alt="Expenses list page" maxHeight="500px" className="w-full p-2" />

***

## Key Features [#key-features]

<Cards>
  <Card title="Creating Expenses" description="Record a business expense, attach receipts, and link customers or invoices" href="/docs/expenses/creating-expenses" />

  <Card title="Extract from Receipt" description="Use AI to scan a receipt and auto-fill expense details" href="/docs/expenses/extract-from-receipt" />

  <Card title="Expense List" description="Search, filter, sort, export, and bulk manage expense records" href="/docs/expenses#expense-list" />

  <Card title="Convert to Invoice" description="Turn one or more expenses into invoice draft line items" href="/docs/expenses#converting-expenses-to-an-invoice" />

  <Card title="Expense Analytics" description="Review spending trends in the Analytics dashboard" href="/docs/analytics#expense-analytics" />
</Cards>

***

## Expense List [#expense-list]

The Expenses page gives you a working list of every expense in the selected organization.

You can see:

* Expense title and linked customer
* Date
* Amount
* Vendor
* Category
* Receipt status
* Actions menu

The top cards show:

* **This Month**: current month spend
* **This Year**: year-to-date spend
* **Top Category**: highest spending category
* **Missing Receipts**: expenses without an attachment

<DocImage src="https://storage.pinebill.app/public/docs/image/Expenses-PineBill-04-28-2026_09_07_AM.png" alt="Expense summary cards" maxHeight="300px" className="w-full p-3" />

***

## Searching, Filtering, and Sorting [#searching-filtering-and-sorting]

Use the filters above the table to narrow the list.

| Control              | What it does                                                     |
| -------------------- | ---------------------------------------------------------------- |
| **Search**           | Searches title, vendor, and notes                                |
| **Date range**       | Shows expenses inside a selected date range                      |
| **Category**         | Filters by one expense category                                  |
| **Receipt status**   | Shows all, only expenses with receipts, or only missing receipts |
| **Sort & Display**   | Sort by date, title, vendor, category, amount, or created date   |
| **Results per page** | Shows 5, 10, 25, or 50 expenses per page                         |

Click **Clear all** to remove active filters.

<DocImage src="https://storage.pinebill.app/public/docs/image/Expenses-PineBill-04-28-2026_09_09_AM.png" alt="Expense detail page" maxHeight="150px" className="h-[100px] w-full p-2" />

***

## Viewing and Editing an Expense [#viewing-and-editing-an-expense]

Click any expense row to open the expense detail page.

From the detail page you can:

* Review amount, currency, category, vendor, payment method, and creator
* See converted amount when the expense currency differs from your organization currency
* Edit the expense
* Edit notes directly
* View linked customer or linked invoice
* Preview image receipts or PDF receipts
* Convert the expense to an invoice draft
* Delete the expense if your role allows it

<DocImage src="https://storage.pinebill.app/public/docs/image/Expense-Details-PineBill-04-28-2026_09_15_AM.png" alt="Expense detail page" maxHeight="300px" className="w-full p-1" />

***

## Converting Expenses to an Invoice [#converting-expenses-to-an-invoice]

Use **Convert to Invoice** when you want to bill a customer for one or more expenses.

### Convert One Expense [#convert-one-expense]

1. Open the actions menu for an expense
2. Click **Convert to Invoice**
3. PineBill opens the invoice generator with that expense added as a line item

You can also open the expense detail page and click **Convert to Invoice**.

### Convert Multiple Expenses [#convert-multiple-expenses]

1. Select expenses from the Expenses table
2. Click **Convert to Invoice**
3. PineBill opens the invoice generator with each selected expense as a line item

<DocImage src="https://storage.pinebill.app/public/docs/image/Expenses-PineBill-04-28-2026_09_18_AM.png" alt="Convert selected expenses to invoice" maxHeight="450px" className="w-full p-2" />

When expenses share the same customer, PineBill selects that customer in the invoice draft. If the expenses use a different currency than your organization currency, PineBill converts the line item amounts before adding them to the draft.

After you create the invoice, PineBill links the converted expenses to the new invoice.

***

## Exporting Expenses [#exporting-expenses]

Click **Export CSV** to download the current filtered expense list.

The export includes:

* Date
* Title
* Vendor
* Category
* Amount and currency
* Converted amount and organization currency
* Payment method
* Customer
* Invoice number
* Notes
* Receipt file name

Use filters before exporting if you only need a specific period, category, or receipt status.

***

## Deleting Expenses [#deleting-expenses]

You can delete one expense from its actions menu or detail page. Organization owners and admins can also select multiple expenses and delete them together.

Deleting an expense also removes its attached receipt. This cannot be undone.

***

## Expense Analytics [#expense-analytics]

Expense totals are also available in &#x2A;*[Analytics](/dashboard/analytics)**. Use expense charts to review spending over time and compare grouped totals by day, week, month, quarter, or year.

<DocImage src="https://storage.pinebill.app/public/docs/image/Analytics-PineBill-04-28-2026_09_33_AM.png" alt="Expense analytics charts" maxHeight="450px" className="w-full p-0" />

***

## Permissions [#permissions]

| Role            | Can view | Can create | Can edit     | Can delete | Can export |
| --------------- | -------- | ---------- | ------------ | ---------- | ---------- |
| **Owner/Admin** | Yes      | Yes        | Any expense  | Yes        | Yes        |
| **Member**      | Yes      | Yes        | Own expenses | No         | No         |

***

## Common Questions [#common-questions]

<Accordions type="single">
  <Accordion title="Why can't I upload my receipt?" id="receipt-upload">
    The file must be an image or PDF and must be 5MB or smaller. Supported image types are PNG, JPG, JPEG, WebP, and GIF.
  </Accordion>

  <Accordion title="Why does the converted amount look different?" id="converted-amount">
    PineBill stores the original expense currency and also converts the amount to your organization
    currency for summaries, analytics, and invoice drafts.
  </Accordion>

  <Accordion title="Why is an invoice missing from the invoice picker?" id="missing-invoice">
    If a customer is selected, the invoice picker only shows invoices connected to that customer.
    Clear the customer field or choose the matching customer.
  </Accordion>

  <Accordion title="Can I recover a deleted expense?" id="recover-deleted-expense">
    No. Deleting an expense permanently removes the expense and its attached receipt.
  </Accordion>
</Accordions>

***

## Related Topics [#related-topics]

* [Creating Expenses](/docs/expenses/creating-expenses) - Add expense records and receipts
* [Extract from Receipt](/docs/expenses/extract-from-receipt) - Scan receipts with AI
* [Creating Invoices](/docs/invoices/creating-invoices) - Review and finish invoice drafts
* [Customers](/docs/customers/adding-customers) - Add customers before linking expenses
* [Analytics](/docs/analytics) - Review expense charts


# Creating Your Account (/docs/getting-started/create-account)







## Overview [#overview]

Sign up using email and password or Google OAuth for instant access.

![Account Creation Screenshot](https://storage.pinebill.app/public/docs/image/docs-auth.png)

## Sign Up Methods [#sign-up-methods]

### Email and Password [#email-and-password]

<Steps>
  <Step>
    ### Sign Up Page [#sign-up-page]

    Visit [pinebill.app/auth/signup](/auth/signup)
  </Step>

  <Step>
    ### Enter Information [#enter-information]

    * Email address
    * Password (see requirements below)
    * Confirm password
  </Step>

  <Step>
    ### Submit [#submit]

    Click "Sign Up" to create your account
  </Step>
</Steps>

### Google OAuth [#google-oauth]

<Steps>
  <Step>
    ### Click "Sign up with Google" [#click-sign-up-with-google]

    On the sign-up page
  </Step>

  <Step>
    ### Choose Account & Authorize [#choose-account--authorize]

    Select your Google account and grant permissions
  </Step>
</Steps>

## Password Requirements [#password-requirements]

* Minimum 8 characters
* At least one uppercase letter (A-Z)
* At least one lowercase letter (a-z)
* At least one number (0-9)

## Email Verification [#email-verification]

After signing up, check your inbox for an email from `noreply@pinebill.app` and click the verification link.

**Email not received?**

* Check spam/junk folder
* Verify correct email address
* Sign in and click "Resend Email" from the banner

## After Sign Up [#after-sign-up]

You'll be guided through organization setup and land on your dashboard with prompts to add customers, products, and create invoices.

## Troubleshooting [#troubleshooting]

<Accordions type="single">
  <Accordion title="Email already exists" id="email-already-exists">
    Try signing in or use "Forgot Password"
  </Accordion>

  <Accordion title="Invalid email format" id="invalid-email-format">
    Check format is `username@domain.com`
  </Accordion>

  <Accordion title="Password too weak" id="password-too-weak">
    Meet requirements above (8+ chars, uppercase, lowercase, number)
  </Accordion>

  <Accordion title="reCAPTCHA failed" id="recaptcha-failed">
    Complete challenge, disable ad blockers, or try different browser
  </Accordion>

  <Accordion title="Google OAuth issues" id="google-oauth-issues">
    Enable third-party cookies, clear cache, disable extensions
  </Accordion>
</Accordions>

## Trial Plan [#trial-plan]

New accounts get 7 days with 50 invoices, 100MB storage, up to 2 team members, and all features. [Upgrade anytime](/pricing).


# Creating Your First Invoice (/docs/getting-started/first-invoice)







## Overview [#overview]

Learn to create and share your first professional invoice, from adding customers and products to generating and sharing the PDF.

<Callout type="tip">
  Add at least one customer and product to your organization first for faster invoice creation.
</Callout>

## What You'll Need [#what-youll-need]

> * Customer name and email
> * Product/service name and price
> * Invoice and due dates
> * Payment method details

<DocImage src="https://storage.pinebill.app/public/docs/image/docs-invoice-first.png" alt="First Invoice Screenshot" />

## Creating Your Invoice [#creating-your-invoice]

<Steps>
  <Step>
    ### Open Invoice Generator [#open-invoice-generator]

    Click "[Create Invoice](/dashboard/generator)" from the dashboard or "Invoices" → "New Invoice" in the sidebar.

    <DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-04-15-2026_03_42_PM.png" alt="First Invoice Screenshot" maxHeight="350px" className="mobile:w-full w-[50%]" />
  </Step>

  <Step>
    ### Add a Customer [#add-a-customer]

    **Option A: Select existing customer** - Click "Select Customer" and search or browse your list.

    **Option B: Add new customer** - Click "Add New Customer", fill in name, email, phone, and address, then save.

    <DocImage src="https://storage.pinebill.app/public/docs/image/invoice-intro-2.png" alt="First Invoice Screenshot" maxHeight="400px" className="mobile:w-full w-[80%] p-0" />
  </Step>

  <Step>
    ### Add Items [#add-items]

    **From catalog**: Click "Add Product", select product, set quantity.

    **Temporary item**: Click "Add Temporary Item", enter name, price, quantity, and optional description (not saved to catalog).

    Add multiple items as needed. Drag to reorder or click trash icon to remove.

    <DocImage src="https://storage.pinebill.app/public/docs/image/invoice-intro-3.png" alt="First Invoice Screenshot" maxHeight="400px" className="mobile:w-full w-[80%] p-0" />
  </Step>

  <Step>
    ### Configure Tax (Optional) [#configure-tax-optional]

    Enable tax, choose type (percentage or fixed amount), enter rate/amount. Tax is calculated on subtotal and shown in preview.
  </Step>

  <Step>
    ### Add Discount (Optional) [#add-discount-optional]

    Enter discount amount (applied to subtotal before tax).
  </Step>

  <Step>
    ### Add Shipping (Optional) [#add-shipping-optional]

    Enter shipping cost (added after tax to final total).
  </Step>

  <DocImage src="https://storage.pinebill.app/public/docs/image/invoice-intro-4.png" alt="First Invoice Screenshot" maxHeight="400px" className="mobile:w-full w-[80%] p-0" />

  <Step>
    ### Add Payment Method [#add-payment-method]

    Click "Add Payment Method", choose type (Bank Transfer, PayPal, Crypto, or Custom), enter details, and optionally set as default. You can add multiple payment methods.
  </Step>

  <DocImage src="https://storage.pinebill.app/public/docs/image/invoice-intro-5.png" alt="First Invoice Screenshot" maxHeight="400px" className="mobile:w-full w-[80%] p-0" />

  <Step>
    ### Set Dates [#set-dates]

    * **Issued Date**: Defaults to today
    * **Due Date**: When payment is expected (use date picker or shortcuts like "Net 30")
  </Step>

  <Step>
    ### Add Optional Details [#add-optional-details]

    * **Payment Terms**: Add conditions (e.g., "Payment due within 30 days")
    * **End Message/Notes**: Personal message or instructions
    * **Digital Signature**: Upload signature image (PNG/JPG)
    * **Custom Fields**: Add PO number, project name, or other custom fields
  </Step>

  <DocImage src="https://storage.pinebill.app/public/docs/image/invoice-intro-6.png" alt="First Invoice Screenshot" maxHeight="380px" className="mobile:w-full w-[80%] p-0" />

  <Step>
    ### Choose Template [#choose-template]

    Select between **Regular** (clean standard layout) or **Bold Professional** (modern design) or one of the other available templates. Preview updates immediately.
  </Step>

  <DocImage src="https://storage.pinebill.app/public/docs/image/invoice-intro-7.png" alt="First Invoice Screenshot" maxHeight="380px" className="mobile:w-full w-[80%] p-0" />

  <Step>
    ### Generate Invoice [#generate-invoice]

    Review all details (customer, items, prices, tax, payment method, dates), then click "Generate Invoice". Your invoice is created with a unique invoice number.
  </Step>

  <DocImage src="https://storage.pinebill.app/public/docs/image/invoice-intro-8a.png" alt="First Invoice Screenshot" maxHeight="380px" className="mobile:w-full w-[80%] p-0" />

  <Step>
    ### Share Invoice [#share-invoice]

    **Option A: Share link** - Click "Share", configure options (expiration, view limit, password), generate link, and send to customer. Recommended for tracking and security.

    **Option B: Download** - Click "Download PDF" and email manually.

    <DocImage src="https://storage.pinebill.app/public/docs/image/invoice-intro-9a.png" alt="First Invoice Screenshot" maxHeight="380px" className="mobile:w-full w-[80%] p-0" />
  </Step>
</Steps>

## Troubleshooting [#troubleshooting]

<Accordions type="single">
  <Accordion title="Invoice won't generate" id="invoice-wont-generate">
    Check all required fields filled, valid prices, due date after issued date
  </Accordion>

  <Accordion title="Preview not updating" id="preview-not-updating">
    Wait a moment or click different field; refresh if frozen
  </Accordion>

  <Accordion title="Can't find invoice" id="cant-find-invoice">
    Check Invoices sidebar, search by customer/number, verify correct organization
  </Accordion>

  <Accordion title="PDF won't download" id="pdf-wont-download">
    Check popup blocker, try different browser, or use share link
  </Accordion>
</Accordions>


# Getting Started with PineBill (/docs/getting-started)





## Who is PineBill For? [#who-is-pinebill-for]

PineBill is designed for:

* **Freelancers** who need to invoice clients quickly and professionally
* **Small Businesses** managing multiple customers and product catalogs
* **Growing Companies** requiring team collaboration and advanced features
* **Enterprises** needing API integration and custom workflows

## What You'll Learn [#what-youll-learn]

This Getting Started guide covers everything you need to begin using PineBill effectively:

<Cards>
  <Card title="Create Your Account" description="Sign up for PineBill and verify your email address" href="/docs/getting-started/create-account" />

  <Card title="Set Up Your Organization" description="Configure your company profile, logo, and branding" href="/docs/getting-started/setup-organization" />

  <Card title="Understanding the Interface" description="Navigate PineBill's dashboard and key features" href="/docs/getting-started/understanding-interface" />

  <Card title="Create Your First Invoice" description="Generate and share your first professional invoice" href="/docs/getting-started/first-invoice" />
</Cards>

## Quick Start Checklist [#quick-start-checklist]

Follow this checklist to get up and running in under 15 minutes:

* [ ] **Create your account** - Sign up with email or Google OAuth
* [ ] **Verify your email** - Confirm your email address
* [ ] **Complete organization setup** - Add company name, address, and logo
* [ ] **Add your first customer** - Create a customer record
* [ ] **Add products or services** - Build your product catalog
* [ ] **Generate your first invoice** - Create and share an invoice
* [ ] **Configure invoice settings** - Customize invoice numbers and defaults

## Learning Path [#learning-path]

We recommend following this path for the best onboarding experience:

### Step 1: Account & Organization Setup (5 minutes) [#step-1-account--organization-setup-5-minutes]

Start by [creating your account](/docs/getting-started/create-account) and [setting up your organization](/docs/getting-started/setup-organization). This establishes your company profile and branding.

### Step 2: Learn the Interface (5 minutes) [#step-2-learn-the-interface-5-minutes]

Familiarize yourself with [PineBill's interface](/docs/getting-started/understanding-interface) to navigate efficiently.

### Step 3: Build Your Data (10 minutes) [#step-3-build-your-data-10-minutes]

Before creating invoices, add:

* [Customers](/docs/customers/adding-customers) - Your clients or customers
* [Products](/docs/products/adding-products) - Your products or services
* [Product Categories](/docs/products/product-categories) - Organization for your catalog

### Step 4: Create Your First Invoice (5 minutes) [#step-4-create-your-first-invoice-5-minutes]

Follow our [complete tutorial](/docs/getting-started/first-invoice) to generate your first professional invoice.

### Step 5: Customize Settings (5 minutes) [#step-5-customize-settings-5-minutes]

Configure [invoice settings](/docs/invoices/invoice-settings) to match your business needs.

## Key Features at a Glance [#key-features-at-a-glance]

### Invoice Generation [#invoice-generation]

Create professional invoices with:

* Multiple templates (Regular, Bold Professional and more...)
* Product-based and hourly billing modes
* Automatic tax, discount, and shipping calculations
* Custom fields for additional information
* Digital signatures

### Customer Management [#customer-management]

Build your customer database with:

* Contact information and addresses
* Unique customer identifiers
* Timezone support for global clients
* Customer history and invoice tracking

### Product Catalog [#product-catalog]

Organize your offerings with:

* Product categories and photos
* SKU/model number tracking
* Pricing management
* Active/inactive status control

### Payment Processing [#payment-processing]

Monitor your business with:

* Invoice status tracking (Draft, Sent, Paid, Overdue, Cancelled)
* Payment date recording
* Multi-currency support
* Revenue analytics

## Prerequisites [#prerequisites]

To use PineBill effectively, you'll need:

* A valid email address for account creation
* Company information (name, address, phone)
* Company logo (optional, but recommended for branding)
* Basic information about your customers and products


# Setting Up Your Organization (/docs/getting-started/setup-organization)







## Overview [#overview]

Your organization represents your business in PineBill, holding all invoices, customers, products, and managing team access, branding, and settings.

<DocImage src="/docs/images/organization-onboard.webp" alt="First Invoice Screenshot" className="mobile:w-full w-full" />

## Onboarding Steps [#onboarding-steps]

<Steps>
  <Step>
    ### Welcome & Organization Name [#welcome--organization-name]

    Enter your business name and business email address,
  </Step>

  <Step>
    ### Company Information (Optional) [#company-information-optional]

    Add phone number and full address,
  </Step>

  <Step>
    ### Default Settings (Optional) [#default-settings-optional]

    Choose currency and timezone,
  </Step>

  <Step>
    ### Company Logo (Optional) [#company-logo-optional]

    Upload your logo for invoice branding.
  </Step>

  <Step>
    ### Complete Setup [#complete-setup]

    Review and finish.
  </Step>
</Steps>

## After Onboarding [#after-onboarding]

Once onboarding is complete, PineBill gives you two main places to manage organization configuration:

* **[Organization](/dashboard/organization)** for the company overview, metadata, and team section
* **[Settings](/dashboard/setup)** for the centralized settings hub

From the Settings hub, organization-related actions are grouped under **Organization Management**:

* **Company Settings** for branding, currency, timezone, and company details
* **Subscription** for billing, plan, and usage
* **Employees** for teammate and role management

The same Settings hub also links to document settings, product configuration, API keys, and API audit logs.

## Configuration Details [#configuration-details]

### Company Name [#company-name]

Use your official business name as it appears on invoices and emails throughout the platform.

### Company Address [#company-address]

Enter your business address with street, city, state/province, postal code, and country. This appears on all invoices.

### Contact Information [#contact-information]

* **Email**: Use a professional business email (e.g., `billing@yourcompany.com`)
* **Phone**: Include country code (e.g., +1 555-123-4567)

### Company Logo [#company-logo]

Upload your logo to add professional branding to invoices.

**Requirements:**

* Formats: PNG, JPG, JPEG, WebP
* Max size: 2 MB
* Recommended: 400x400 pixels or larger, transparent PNG

<Callout type="tip">
  You can skip this and add it later. Your organization name will appear on invoices instead.
</Callout>

### Default Currency [#default-currency]

Select your primary currency (USD, EUR, GBP, CAD, AUD, and [150+ others](/supported-currencies)). This becomes the default for new invoices, but you can change it per invoice if needed.

### Timezone [#timezone]

Your timezone affects invoice dates, scheduled tasks, and analytics. Choose your region and closest major city (e.g., "New York", "London", "Seoul").

<Callout type="warning">
  Choose carefully - changing timezone after creating invoices may affect date displays.
</Callout>

## Editing Settings Later [#editing-settings-later]

To update your company profile after onboarding:

1. Open &#x2A;*[Settings](/dashboard/setup)**
2. Click **Company Settings**
3. Click **Edit Settings**
4. Update the form fields
5. Click **Save Organization Settings**

You can also start from &#x2A;*[Organization](/dashboard/organization)** and use the **Settings** button in the page header.

## Troubleshooting [#troubleshooting]

<Accordions type="single">
  <Accordion title="Logo won't upload" id="logo-wont-upload">
    Check file format (PNG/JPG/JPEG/WebP), verify the file is under 2 MB, then try again.
  </Accordion>

  <Accordion title="Settings not saving" id="settings-not-saving">
    Make sure you entered valid values, then click **Save Organization Settings**. Invalid email
    formats and oversized fields will block the save.
  </Accordion>

  <Accordion title="Timezone incorrect" id="timezone-incorrect">
    Search for different city in same timezone, verify UTC offset
  </Accordion>
</Accordions>


# Notifications (/docs/notifications)





## Overview [#overview]

PineBill records notification events in your dashboard and can also deliver them by email and to Slack.

| Channel       | What it does                                                     |
| ------------- | ---------------------------------------------------------------- |
| **Dashboard** | Always on. Every event is recorded in your notification history. |
| **Email**     | Optional per event. Toggle individual events on or off.          |
| **Slack**     | Optional per event. Route events to specific Slack channels.     |

You manage all of this from **Dashboard → Setup → Notifications**.

## Email Preferences [#email-preferences]

Each email-enabled event has its own toggle:

* **Invoice Email Clicks** — a customer opens an invoice email link
* **Estimate Email Clicks** — a customer opens an estimate email link
* **Estimate Accepted** — a customer accepts an estimate
* **Estimate Declined** — a customer declines an estimate

<Callout type="info">
  Dashboard notification history is still recorded even when email is disabled.
</Callout>

## Slack [#slack]

Connect a Slack workspace to route events to channels of your choice. See [Slack Notifications](/docs/notifications/slack) for the full setup.


# Slack Notifications (/docs/notifications/slack)





## Overview [#overview]

Connect a Slack workspace to PineBill and send notification events to the channels you choose. Each event is routed independently, so you can send invoice activity to one channel and estimate activity to another.

<DocImage src="https://storage.pinebill.app/public/docs/image/Notification-Settings-PineBill-05-29-2026_11_15_AM.png" alt="Slack notifications settings" maxHeight="400px" className="w-full p-0" />

<Callout type="info">
  Only the **organization owner** can connect, configure, or disconnect Slack.
</Callout>

***

## Connect Slack [#connect-slack]

1. Go to &#x2A;*Dashboard → Setup → [Notifications](/dashboard/setup/notifications)**.
2. In the **Slack Notifications** card, click **Add to Slack**.
3. Approve the requested permissions in Slack and pick the workspace to install into.
4. You're redirected back to PineBill with the workspace connected.

<DocImage src="https://storage.pinebill.app/public/docs/image/Notification-Settings-PineBill-05-29-2026_11_21_AM.png" alt="Add to Slack button" maxHeight="400px" className="w-full p-0" />

***

## Route Events to Channels [#route-events-to-channels]

Once connected, each notification event shows a channel selector. Pick a channel to start sending that event, or choose **Don't send** to leave it off.

| Event                      | Sent when                               |
| -------------------------- | --------------------------------------- |
| **Invoice email clicked**  | A customer opens an invoice email link  |
| **Estimate email clicked** | A customer opens an estimate email link |
| **Estimate accepted**      | A customer accepts an estimate          |
| **Estimate declined**      | A customer declines an estimate         |
| **Security alert**         | Important account and security updates  |
| **System announcement**    | Product and service announcements       |

<DocImage src="https://storage.pinebill.app/public/docs/image/Notification-Settings-PineBill-05-29-2026_11_23_AM.png" alt="Routing events to Slack channels" maxHeight="400px" className="w-full p-0" />

***

## Don't See a Channel? [#dont-see-a-channel]

* **Public channels** appear automatically — no invite needed.
* **Private channels** appear only after you invite the PineBill app to them.

To add the app to a private channel, open it in Slack and type `/invite @PineBill`, then click **Refresh** in the Slack Notifications card to reload the channel list.

<Callout type="info">
  If a channel you've routed events to is later archived or deleted in Slack, that event
  automatically resets to **Don't send**. Pick a new channel to resume delivery.
</Callout>

***

## Disconnect Slack [#disconnect-slack]

Click **Disconnect** in the Slack Notifications card to stop sending notifications to Slack. This revokes PineBill's access to your workspace.

<Callout type="info">
  Your channel mappings are saved. If you reconnect the same workspace, your previous routing is
  restored.
</Callout>


# Organization (/docs/organization)





## Quick Start [#quick-start]

The Organization page is the overview screen for your workspace. It shows your company profile, key metadata, and team members, and it includes a direct path to **Company Settings**.

<DocImage src="https://storage.pinebill.app/public/docs/image/My-Organization-04-15-2026_04_24_PM.png" alt="Organization overview page" maxHeight="500px" className="w-full p-0" />

***

## Company Information [#company-information]

The top card displays your company details:

### Company Logo [#company-logo]

* Displays uploaded company logo (if set)
* 96x96px preview
* Falls back to company initials if no logo is uploaded
* Updated from [Organization Settings](/dashboard/organization/settings)

### Company Details [#company-details]

| Field           | Description                                   |
| --------------- | --------------------------------------------- |
| Company Name    | Your business name                            |
| Email           | Company email address (clickable mailto link) |
| Phone           | Company phone number (clickable tel link)     |
| Address         | Full business address (multi-line)            |
| Timezone        | Organization timezone in IANA format          |
| Created         | Date when organization was created            |
| Organization ID | Unique ID shown in a code block               |

### Organization ID [#organization-id]

* Unique identifier for your organization
* Used for API integrations and support
* Displayed directly on the overview card

***

## Team Members [#team-members]

Team member management appears below company information.

**Note**: Solo plan users do not see the team management section. Member management is available on supported multi-user plans.

### Member List [#member-list]

Table showing all organization members:

| Column  | Information                                |
| ------- | ------------------------------------------ |
| Name    | Member's display name                      |
| Email   | Member's email address                     |
| Role    | ADMIN, MEMBER, or GUEST                    |
| Status  | Active or Pending invitation               |
| Joined  | Date when member joined                    |
| Actions | Edit role, resend invite, or remove member |

<DocImage src="https://storage.pinebill.app/public/docs/image/Organizations-12-01-2025_09_13_PM.webp" alt="Team members list" maxHeight="500px" className="w-full p-0" />

### Member Roles [#member-roles]

| Role       | Permissions                                                 |
| ---------- | ----------------------------------------------------------- |
| **ADMIN**  | Full access. Can manage organization, members, and all data |
| **MEMBER** | Can create and manage invoices, customers, products         |

### Inviting Members [#inviting-members]

1. Enter email address
2. Select role (ADMIN, MEMBER, or GUEST)
3. Click **Send Invitation**
4. Invitation email sent to the address
5. Member appears in list with "Pending" status

<DocImage src="https://storage.pinebill.app/public/docs/image/Organizations-12-01-2025_09_15_PM.webp" alt="Invite member form" maxHeight="400px" className="w-full p-0" />

**Invitation expires**: Invitations expire after 7 days.

### Managing Members [#managing-members]

**Resend Invitation:**

* For pending members only
* Click resend icon
* New invitation email sent

**Remove Member:**

1. Click delete icon
2. Confirm deletion
3. Member immediately loses access
4. Cannot remove yourself
5. Organization owner cannot be removed

***

## Settings Button [#settings-button]

Click the **Settings** button in the top-right corner to open [Organization Settings](/dashboard/organization/settings), where owners can edit company information, upload a logo, review billing, and access destructive organization actions.

You can also reach the same page from the central [Settings hub](/dashboard/setup) under **Company Settings**.

<DocImage src="https://storage.pinebill.app/public/docs/image/My-Organization-04-15-2026_04_25_PM.png" alt="Invite member form" maxHeight="400px" className="w-full p-2" />

***

## Related Topics [#related-topics]

* [Organization Settings](/docs/organization/organization-settings) - Edit company details
* [Set Up Your Organization](/docs/getting-started/setup-organization) - Complete onboarding and configure your workspace
* [Subscription Plans](/docs/subscription) - Upgrade to add team members


# Organization Settings (/docs/organization/organization-settings)







## Quick Start [#quick-start]

Organization Settings is the company configuration page for your workspace. You can open it from either of these entry points:

* **[Organization](/dashboard/organization)** → **Settings**
* **[Settings](/dashboard/setup)** → **Company Settings**

**Permissions**: Only organization owners can edit settings. Members and guests can view but not modify.

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-04-15-2026_04_26_PM.png" alt="Organization settings entry points" maxHeight="400px" className="w-full p-2" />

***

## Page Sections [#page-sections]

The current page is organized into four main sections:

### Company Information [#company-information]

This section contains the editable company profile form:

* Company Name
* Company Email
* Company Phone
* Default Currency
* Timezone
* Company Address

Owners can click **Edit Settings** to unlock the form. Non-owners see the same information in read-only mode.

### Company Logo [#company-logo]

The logo section includes:

* A 128×128 preview area
* Upload dropzone with drag-and-drop support
* File picker link
* Delete button when a logo already exists

### Subscription & Billing [#subscription--billing]

This section links to &#x2A;*[Manage Subscription](/dashboard/subscription)** so owners can review plan details, usage, and billing.

If the organization has access to priority support, the same page also shows a **Contact Live Support** action.

### Danger Zone [#danger-zone]

Owners also see a destructive **Delete Organization** section. Deleting an organization requires typing `delete` in the confirmation dialog before the action is enabled.

***

## Editing Company Information [#editing-company-information]

<Steps>
  <Step>
    ### Open Edit Mode [#open-edit-mode]

    1. Open **Organization Settings**
    2. In the **Company Information** card, click **Edit Settings**
    3. The form fields become editable
  </Step>

  <Step>
    ### Update Fields [#update-fields]

    | Field            | Required | Max Length | Description                             |
    | ---------------- | -------- | ---------- | --------------------------------------- |
    | Company Name     | No       | 255 chars  | Business name on invoices               |
    | Company Email    | No       | -          | Primary business email (must be valid)  |
    | Company Phone    | No       | 50 chars   | Business phone number (any format)      |
    | Company Address  | No       | 500 chars  | Full address (multi-line textarea)      |
    | Default Currency | No       | -          | Currency for invoices and analytics     |
    | Timezone         | No       | -          | IANA timezone (e.g., America/New\_York) |

    **Note**: The form accepts blank values for optional fields, but if you enter a company name it must be at least 1 character and at most 255 characters.
  </Step>

  <Step>
    ### Save Changes [#save-changes]

    1. Click **Save Organization Settings** button
    2. The changes are saved immediately
    3. The form returns to read-only mode
    4. A success toast confirms the update

    **Cancel**: Click **Cancel** to discard unsaved changes and reset the form to the current saved values.
  </Step>
</Steps>

***

## Company Logo [#company-logo-1]

### Uploading Logo [#uploading-logo]

1. Scroll to "Company Logo" section
2. Drag and drop an image file **or** click **browse files**
3. Select image file
4. Upload starts automatically
5. Logo appears in preview area

**File Requirements:**

* Formats: PNG, JPG, JPEG, WebP
* Max size: 2MB
* Recommended: 400x400px square image

### Logo Preview [#logo-preview]

* 128x128px preview shown
* Current logo displays if set
* "No logo" placeholder if not set
* Owners can remove the existing logo with the delete button on the preview

***

## Default Currency [#default-currency]

**Purpose**: Sets the default currency for:

* New invoices
* Analytics calculations
* Product prices

**Multi-currency**: You can still create invoices in different currencies. This just sets the default.

***

## Subscription & Billing [#subscription--billing-1]

### Current Plan [#current-plan]

Displays your active subscription plan:

* Click **Manage Subscription** to view plan details
* Change plans or update billing information
* View usage and limits

### Priority Support [#priority-support]

If priority support is available for your plan, the page shows a support card with direct access to live chat.

Click **Contact Live Support** to open chat from the settings page.

***

## Permission Notes [#permission-notes]

### Owner-Only Actions [#owner-only-actions]

Only organization owners can:

* Edit company information
* Upload/delete company logo
* Change default currency
* Update timezone
* Delete the organization

***

## Common Errors [#common-errors]

<Accordions type="single">
  <Accordion title="Company name is required" id="name-required">
    **Problem**: The form rejects an empty company name when a value is provided but does not meet validation rules.

    **Solution**: Enter a valid company name or clear the field entirely.
  </Accordion>

  <Accordion title="Must be a valid email" id="invalid-email">
    **Problem**: Email format is incorrect.

    **Solution**: Enter a valid email address (e.g., [company@example.com](mailto:company@example.com)) or leave the field empty.
  </Accordion>

  <Accordion title="File size exceeds 2MB" id="file-too-large">
    **Problem**: Logo file is larger than 2MB.

    **Solution**:

    * Compress the image using an online tool
    * Resize to 400x400px or smaller
    * Convert to WebP format for smaller file size
  </Accordion>

  <Accordion title="Only JPEG, JPG, PNG, and WebP images are allowed" id="invalid-format">
    **Problem**: Uploaded file is not a supported image format.

    **Solution**: Convert your file to PNG, JPG, or WebP format.
  </Accordion>

  <Accordion title="Upload failed" id="upload-failed">
    **Problem**: Logo upload encountered an error.

    **Solution**:

    * Check internet connection
    * Verify file size under 2MB
    * Try a different image
    * Refresh page and try again
  </Accordion>

  <Accordion title="Only organization owners can modify settings" id="not-owner">
    **Problem**: You are not the organization owner.

    **Solution**: Ask the organization owner to:

    * Make you an owner
    * Or update the settings for you
  </Accordion>

  <Accordion title="Delete organization button is disabled" id="delete-disabled">
    **Problem**: The delete confirmation action stays disabled.

    **Solution**: Type `delete` exactly into the confirmation field to enable the final action.
  </Accordion>
</Accordions>

***

## Related Topics [#related-topics]

* [Organization Overview](/docs/organization) - View organization details and open Company Settings
* [Settings Hub](/dashboard/setup) - Open all configuration areas from one page
* [Creating Invoices](/docs/invoices/creating-invoices) - Company info appears on invoices
* [Subscription Plans](/docs/subscription) - Upgrade for more features


# Payment Methods (/docs/payments)







## Quick Start [#quick-start]

Payment methods are displayed on invoices to show customers how they can pay. Navigate to &#x2A;*[Payment Methods](/dashboard/payment-methods)** to manage your payment options.

<DocImage src="https://storage.pinebill.app/public/docs/image/Manage-Payments-PineBill-04-15-2026_04_04_PM.png" alt="Payment methods list page" maxHeight="500px" className="w-full p-0" />

***

## Payment Method Types [#payment-method-types]

| Type       | Fields                                                                                           | Notes                             |
| ---------- | ------------------------------------------------------------------------------------------------ | --------------------------------- |
| **Bank**   | Bank Name, Account Name, Account Number, SWIFT, IBAN, Routing Number, Sort Code, Branch, Address | Most common for business payments |
| **PayPal** | Email address                                                                                    | Simple, single field              |
| **Crypto** | Currency (BTC, ETH, etc.), Wallet Address                                                        | For cryptocurrency payments       |
| **Custom** | Custom label-value pairs                                                                         | Any other payment method          |

***

## Creating Payment Methods [#creating-payment-methods]

<Steps>
  <Step>
    ### 1. Open Create Dialog [#1-open-create-dialog]

    1. Navigate to &#x2A;*[Payment Methods](/dashboard/payment-methods)**
    2. Click **Add Payment Method** button
    3. Payment method dialog opens

    <DocImage src="https://storage.pinebill.app/public/docs/image/Manage-Payments-PineBill-12-01-2025_08_35_PM.webp" alt="Add payment method button location" maxHeight="400px" className="w-full p-0" />
  </Step>

  <Step>
    ### 2. Select Type and Fill Details [#2-select-type-and-fill-details]

    **Required Fields (All Types):**

    * Payment Method Name (max 100 characters)
    * Type selection (Bank, PayPal, Crypto, or Custom)

    **Type-Specific Fields:**

    **Bank Transfer:**

    ```
    Bank Name: Chase Bank *
    Account Name: Acme Corporation *
    Account Number: 1234567890 *
    SWIFT Code: CHASUS33 (optional)
    IBAN: US12 CHAS 0000 1234 5678 90 (optional)
    Routing Number: 021000021 (optional)
    Sort Code: 00-00-00 (optional)
    Bank Branch: Main Branch (optional)
    Bank Address: 123 Wall St, New York (optional)
    ```

    **PayPal:**

    ```
    PayPal Email: payments@company.com *
    ```

    **Cryptocurrency:**

    ```
    Currency: BTC *
    Wallet Address: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh *
    ```

    **Custom:**

    ```
    (Add unlimited custom fields)
    Label: Venmo Username
    Value: @company-payments
    ```

    <DocImage src="https://storage.pinebill.app/public/docs/image/Manage-Payments-PineBill-12-01-2025_08_41_PM.webp" alt="Bank payment method creation form" maxHeight="500px" className="w-full p-0" />
  </Step>

  <Step>
    ### 3. Set Options [#3-set-options]

    **Default Payment Method:**

    * Check "Set as default" to auto-select this method in new invoices
    * Only one payment method can be default at a time
    * Setting a new default removes the flag from the previous one
  </Step>

  <Step>
    ### 4. Save [#4-save]

    1. Click **Create Payment Method**
    2. Payment method is saved
    3. Available for use in invoices
  </Step>
</Steps>

***

## Using Payment Methods in Invoices [#using-payment-methods-in-invoices]

### Adding to New Invoices [#adding-to-new-invoices]

When creating an invoice:

1. Go to the **Payment Methods** tab
2. Click **Select Payment Methods**
3. Choose one or more payment methods
4. Default payment method is pre-selected
5. Selected methods appear on the generated invoice PDF

<DocImage src="https://storage.pinebill.app/public/docs/image/Create-Invoice-PineBill-12-01-2025_08_45_PM.png" alt="Selecting payment methods during invoice creation" maxHeight="400px" className="w-full p-0" />

### Multiple Payment Methods [#multiple-payment-methods]

* Invoices can have multiple payment methods
* All selected methods appear on the PDF
* Customers can choose their preferred option

### No Payment Methods [#no-payment-methods]

* Payment methods are optional
* Invoices can be created without payment methods
* Useful for internal invoices or specific billing arrangements

***

## Custom Payment Methods [#custom-payment-methods]

Custom payment methods support unlimited label-value fields.

### Creating Custom Fields [#creating-custom-fields]

1. Select **Custom** type
2. Click **Add Custom Field**
3. Enter label (e.g., "Zelle Email")
4. Enter value (e.g., "[payments@company.com](mailto:payments@company.com)")
5. Repeat for additional fields
6. Click **Save Payment Method**

**Example Custom Payment Method:**

```
Name: Mobile Payment
Type: Custom
Fields:
  - Zelle Email: payments@company.com
  - Cash App: $CompanyPayments
  - Venmo: @company-payments
```

<DocImage src="https://storage.pinebill.app/public/docs/image/Manage-Payments-PineBill-12-01-2025_08_41_PM.webp" alt="Bank payment method creation form" maxHeight="500px" className="w-full p-0" />

### Editing Custom Fields [#editing-custom-fields]

1. Edit the custom payment method
2. Add, remove, or modify field labels and values
3. Save changes

***

## Common Errors [#common-errors]

<Accordions type="single">
  <Accordion title="Payment method name is required" id="name-required">
    **Problem**: Payment method name field is empty.

    **Solution**: Enter a descriptive name for the payment method (e.g., "Company Bank Account", "PayPal Business").
  </Accordion>

  <Accordion title="Required field missing" id="required-field">
    **Problem**: A required field for the selected type is empty.

    **Solution**:

    * **Bank**: Must fill Bank Name, Account Name, and Account Number
    * **PayPal**: Must fill Email
    * **Crypto**: Must fill Currency and Wallet Address
    * **Custom**: Must add at least one custom field
  </Accordion>

  <Accordion title="Invalid email address" id="invalid-email">
    **Problem**: PayPal email format is incorrect.

    **Solution**: Enter a valid email address (e.g., [payments@company.com](mailto:payments@company.com)).
  </Accordion>

  <Accordion title="Cannot delete payment method" id="cannot-delete">
    **Problem**: Payment method is used in existing invoices or is set as default.

    **Solution**:

    * If default: Unset the default flag or set another payment method as default first
    * If used in invoices: Cannot delete. Set to inactive instead to hide from future use
  </Accordion>
</Accordions>

***

## Related Topics [#related-topics]

* [Creating Invoices](/docs/invoices/creating-invoices) - Add payment methods to invoices
* [Invoice Settings](/docs/invoices/invoice-settings) - Configure default payment methods


# Creating Invoices (/docs/invoices/creating-invoices)





## Quick Start [#quick-start]

Access the invoice generator from your dashboard by clicking "Plus" button on the sidebar or "Create Invoice" button from Invoices pages.

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoices-List-PineBill-04-15-2026_03_46_PM-04-15-2026_03_49_PM.png" alt="Invoice Generator Overview" maxHeight="500px" className="w-full p-0" />

***

## User Interface [#user-interface]

The invoice generator interface consists of 3 main regions:

1. **Parameters Area**: Tabbed interface where you configure invoice details (Customer, Products, Invoice Details, Payment Methods, Company Info)
2. **Preview Area**: Visual preview of your invoice (note: this is not real-time PDF generation, but an HTML preview)
3. **Toolbar Area**: Top bar with Create Invoice button, options menu, and template/format settings

<DocImage src="https://storage.pinebill.app/public/docs/image/ic-areas.webp" alt="Invoice Generator UI Regions" maxHeight="450px" className="w-full p-0" />

***

## Toolbar Features [#toolbar-features]

The toolbar at the top of the invoice generator provides quick access to display options and the create button.

<DocImage src="https://storage.pinebill.app/public/docs/image/CCreate-Invoice-PineBill-01-05-2026_11_04_PM.png" alt="Template Selector" maxHeight="300px" className="w-full p-0" />

### Live Preview [#live-preview]

Toggle live preview from the options menu to see your invoice in real-time as you make changes.

### Templates [#templates]

Select your invoice template from the options menu (top right):

* **Classic**: Clean, traditional design
* **Bold Professional**: Contemporary with bold accents
* **Mono**: Minimalist, monospace style
* **Startup Modern**: Sleek, modern look for startups

Each template includes all the same information with different visual styling. [Learn more about templates](/docs/invoices/invoice-templates).

### Date Formats [#date-formats]

Select date format from options menu. Available formats:

| Format 1   | Format 2       | Format 3     |
| ---------- | -------------- | ------------ |
| MM/DD/YYYY | Month DD, YYYY | Mon DD, YYYY |
| DD/MM/YYYY | DD Month YYYY  | DD Mon YYYY  |
| YYYY-MM-DD |                |              |

### Invoice Language [#invoice-language]

Select the language for your invoice PDF labels and text. This controls how section titles, column headers, and standard text appear on the generated PDF.

**PineBill Supported Languages:**

| Language                      | Language          | Language           |
| ----------------------------- | ----------------- | ------------------ |
| Arabic (العربية)              | English           | Italian (Italiano) |
| Azerbaijani (Azərbaycan dili) | French (Francais) | Japanese (日本語)     |
| Chinese (中文)                  | German (Deutsch)  | Korean (한국어)       |
| Portuguese (Portugues)        | Spanish (Espanol) | Turkish (Türkçe)   |

<Callout type="info">
  The language setting only affects PDF labels (like "Bill To", "Invoice Date", "Total"). Your
  custom content such as product names, descriptions, and messages remains unchanged.
</Callout>

Set your default language in [Invoice Settings](/docs/invoices/invoice-settings) to save time when creating invoices.

***

## Step-by-Step Guide [#step-by-step-guide]

## Requirements [#requirements]

To create an invoice you must have:

| Requirement           | Status      | Details                  |
| --------------------- | ----------- | ------------------------ |
| Customer              | Required    | At least one customer    |
| Product/Service Items | Required    | At least one line item   |
| Invoice Number        | Auto-filled | Automatically generated  |
| Issue Date            | Auto-filled | Defaults to current date |

The invoice generator has 5 tabs. Fill them out to create your invoice.

### 1. Products/Services (Required) [#1-productsservices-required]

Add items to your invoice using the **inline product row** at the bottom of the products table:

* **Type to Search**: Start typing a product name in the inline row. An autocomplete dropdown appears with matching products from your catalog. Recent products are shown automatically when you click the field.
* **Select from Catalog**: Click a product in the dropdown to instantly add it to your invoice with its saved name, model, and price.
* **Create Inline Temporary Item**: Type a new product name that doesn't match any catalog product, then fill in the model, quantity, and price fields in the same row. Press **Enter** or click outside to add it. Temporary items are not saved to your catalog.
* **[Browse All Products](/docs/products/product-selection)**: Click "Browse All Products" at the bottom of the autocomplete dropdown to open the full product selector with filters, categories, and multi-select.

<DocImage src="https://storage.pinebill.app/public/docs/image/invoice-intro-3.png" alt="Products Tab" maxHeight="400px" className="w-full p-0" />

### Selected Product Features: [#selected-product-features]

* **Drag to Reorder**: Click and drag items to change their order on the invoice
* **Inline Editing**: Click any quantity or unit price to edit it directly in the table. For temporary items, you can also click to edit the name and model.

<DocImage src="https://storage.pinebill.app/public/docs/image/ci-items-attr.webp" alt="Products Tab Features" maxHeight="400px" className="w-full p-0" />

**Additional Costs:**

* **Shipping**: Add delivery or shipping costs
* **Discount**: Apply a fixed discount amount
* **Tax**: Configure tax rate and type (see [Calculations](/docs/invoices/creating-invoices#calculations) section)

**Optional:**

* **Assign to Employee**: Link invoice to a specific employee, later on you analyze employee performance based on invoiced amounts.
* **Invoice Mode**: Switch between **PRODUCT** and **HOURLY** modes using the toggle in the tab header.

### Invoice Modes [#invoice-modes]

Choose between two billing modes:

| Mode        | Best For                                  | Line Items Display    |
| ----------- | ----------------------------------------- | --------------------- |
| **PRODUCT** | Physical/digital products, fixed services | Quantity × Unit Price |
| **HOURLY**  | Time-based work, consulting               | Hours × Hourly Rate   |

***

### 2. Customer (Required) [#2-customer-required]

Select a customer from your saved customers list. You must have at least one customer to create an invoice.

<DocImage src="https://storage.pinebill.app/public/docs/image/ci-customer-selection.png" alt="Customer Selection Tab" maxHeight="400px" className="w-full p-0" />

**- Option A: Select existing customer** - Click "Select Customer" and search or browse your list.

**- [Option B: Add new customer](/docs/customers/adding-customers)** - Click "Add New Customer", fill in name, email, phone, and address, then save.

<DocImage src="https://storage.pinebill.app/public/docs/image/ci-customer-list.webp" alt="Customer List Popup" maxHeight="400px" className="w-full p-0" />

**Included Customer Information:**

| Field                 | Value                                             |
| --------------------- | ------------------------------------------------- |
| Issued To (Full Name) | Vicki K. Greene                                   |
| Identifier            | 1234                                              |
| Address               | 3594 Rollins Road, Alma, NE 68920                 |
| Zip Code              | 68920                                             |
| Email                 | [sample@pinebill.app](mailto:sample@pinebill.app) |
| Phone                 | +82 123-456-789                                   |

***

### 3. Invoice Details [#3-invoice-details]

Configure invoice metadata:

* **Invoice Number**: Click "Generate" to auto-create a unique number, the default behavior of Invoice number generation can be configured in [Invoice Settings](/docs/invoices/invoice-settings).
* **Issue Date**: When the invoice is created (Required)
* **Due Date**: Payment deadline (Optional)
* **Currency**: Select from available currencies, default is set in organization settings. Changing the currency will affect calculations and display of all invoice values. Default can be set in [Invoice Settings](/docs/invoices/invoice-settings).
* **Currency Format**: Choose how amounts are displayed: **Symbol** (`$1,234.50`), **Localized symbol** (`US$1,234.50`), **Currency code** (`USD 1,234.50`), **Currency name** (`1,234.50 US dollars`), or **Accounting** (`($1,234.50)` for negative values).
* **Terms of Payment**: Payment conditions (e.g., "Net 30", "50% upfront"), default can be set in [Organization Settings](/docs/organization/organization-settings).
* **End Message**: Custom note at bottom of invoice, default can be set in [Invoice Settings](/docs/invoices/invoice-settings).
* **Custom Data Fields**: Add unlimited label-value pairs (e.g., PO Number, Project ID), default fields can be configured in [Invoice Settings](/docs/invoices/invoice-settings).

<DocImage src="https://storage.pinebill.app/public/docs/image/ci-invoice-setttings.png" alt="Invoice Details Tab" maxHeight="400px" className="w-full p-0" />

***

### 4. Payment Methods [#4-payment-methods]

Select one or more payment methods from your saved payment methods list. Payment methods are &#x2A;**optional*** but recommended to provide customers with payment options. You can configure default payment methods in [Payment Methods](/docs/payments).

* **Bank Transfer**: Bank account details
* **PayPal**: PayPal email
* **Cryptocurrency**: Wallet address
* **Custom**: Any other payment method

<DocImage src="https://storage.pinebill.app/public/docs/image/Create-Invoice-PineBill-11-30-2025_08_23_PM.png" alt="Payment Methods Tab" maxHeight="400px" className="w-full p-0" />

***

### 5. Company Information [#5-company-information]

Your company details are automatically filled from your organization settings:

* Company name, address, email, phone
* **Logo**: Only if uploaded in [Organization Settings](/docs/organization/organization-settings)
* **Signature/Stamp**: Add a default signature for all invoices

All these details can be configured in [Organization Settings](/docs/organization/organization-settings).

<DocImage src="https://storage.pinebill.app/public/docs/image/Create-Invoice-PineBill-11-30-2025_08_31_PM.png" alt="Company Information Tab" maxHeight="400px" className="w-full p-0" />

***

### 6. Creating the Invoice [#6-creating-the-invoice]

Once all required fields are filled:

<DocImage src="https://storage.pinebill.app/public/docs/image/Create-Invoice-PineBill-11-30-2025_09_15_PM.png" alt="Company Information Tab" maxHeight="400px" className="w-full p-0" />

1. Click "Create Invoice" button (top right)
2. PDF is automatically generated
3. Invoice is saved with DRAFT status
4. You're redirected to the invoice detail page

From there you can:

* Download the PDF
* Share the invoice
* Update the status
* Edit if needed

***

## Calculations [#calculations]

### Tax Configuration [#tax-configuration]

Two tax types available:

* **Percentage (%)**: Tax calculated as percentage of subtotal
* **Fixed Amount**: Flat tax amount

**Tax Included Toggle:**

* **ON**: Prices already include tax (tax is extracted from total)
* **OFF**: Tax is added on top of prices (default)

### Calculation Formula [#calculation-formula]

```
Subtotal = Sum of (Quantity × Unit Price)
After Discount = Subtotal - Discount
Tax Amount = After Discount × (Tax Rate / 100)  [or Fixed Amount]
Grand Total = After Discount + Tax + Shipping
```

## Advanced Features [#advanced-features]

### Custom Fields [#custom-fields]

Add any additional information to your invoices:

1. Click "Add Custom Field" in Invoice Details tab
2. Enter label (e.g., "PO Number")
3. Enter value
4. Repeat for multiple fields

<DocImage src="https://storage.pinebill.app/public/docs/image/Create-Invoice-PineBill-11-30-2025_09_12_PM.png" alt="Custom Fields" maxHeight="400px" className="w-full p-0" />

***

## Related Topics [#related-topics]

* [Invoice Components](/docs/invoices/invoice-components) - Understand invoice structure
* [Invoice Statuses](/docs/invoices/invoice-statuses) - Manage invoice lifecycle
* [Invoice Templates](/docs/invoices/invoice-templates) - Choose template styles
* [Invoice Settings](/docs/invoices/invoice-settings) - Configure defaults and number generation


# Document Footer (/docs/invoices/document-footer)





## Document Footer [#document-footer]

The footer is a block of rich content rendered at the bottom of **every page** of a generated PDF. The same footer system is shared by **invoices and estimates** — one editor, one set of defaults.

Use it for things like legal disclaimers, return policies, bank/registration details, a thank-you note, or a small logo.

<DocImage src="https://storage.pinebill.app/public/docs/image/Screenshot%202026-06-28%20213528.png" alt="A document footer rendered at the bottom of an invoice page" maxHeight="440px" className="w-full p-0" />

## Where to set it [#where-to-set-it]

There are two places, and they work together:

* **Default footer (Settings → Document Settings):** applied automatically to **new** invoices and estimates. Set this once and every new document starts with it.
* **Per-document footer (in the generator):** open the **Details** section while creating or editing an invoice or estimate and edit the **Footer** field. This overrides the default for that single document.

<DocImage src="https://storage.pinebill.app/public/docs/image/Document-Settings-PineBill-06-28-2026_09_40_PM.png" alt="The Document Settings page with the shared footer editor" maxHeight="440px" className="w-full p-0" />

<Callout type="info">
  Changing the default footer in **Document Settings** does **not** change invoices or estimates you
  already created — only documents made afterward. To update an existing document, edit it and
  change its footer directly.
</Callout>

## What you can add [#what-you-can-add]

The footer uses a rich-text editor. The toolbar supports:

* **Title** and **Subtitle** headings
* **Bold**, **Italic**, and **Underline**
* **Text color**
* **Links** — add, edit, or remove. URLs without a scheme default to `https://`.
* **Images** — upload from the toolbar, or paste/drag an image straight into the editor.

**Images:** PNG, JPEG, or WebP, up to **2 MB**. After inserting an image, drag its corner handles to resize — the aspect ratio is locked so logos don't distort.

## How it renders [#how-it-renders]

* The footer appears centered at the bottom of every page, in small print.
* The bottom page margin **auto-fits** the footer's height, so nothing overlaps your content or gets cut off.
* Very tall footers are capped so they can't take over the page.

## Notes [#notes]

* Footer content is sanitized on save and again before the PDF is generated. Only basic formatting tags survive; scripts and arbitrary styles are stripped.
* Uploaded images are stored on PineBill storage and served from there — external image URLs are not allowed.

## Related Topics [#related-topics]

* [Creating Invoices](/docs/invoices/creating-invoices)
* [Creating Estimates](/docs/estimates/creating-estimates)
* [Invoice Components](/docs/invoices/invoice-components)


# Editing Invoices (/docs/invoices/editing-invoices)





## Overview [#overview]

PineBill allows you to edit invoices to correct errors, update information, or adjust details after creation. There are two ways to edit invoices: full editing through the invoice generator, or quick inline edits directly on the invoice details page.

***

## Editing Restrictions [#editing-restrictions]

Not all invoices can be edited. The table below shows which statuses allow editing:

| Status    | Can Edit | Notes                                      |
| --------- | -------- | ------------------------------------------ |
| DRAFT     | Yes      | Full editing available                     |
| SENT      | Yes      | Consider notifying the customer of changes |
| OVERDUE   | Yes      | You may also want to update the status     |
| PAID      | Yes      | Limited - mainly for corrections           |
| CANCELLED | No       | Cannot edit cancelled invoices             |

<Callout type="info">
  While paid invoices can be edited, it's generally recommended to only make corrections to maintain
  accurate records. For significant changes, consider creating a new invoice instead.
</Callout>

***

## Full Invoice Editing [#full-invoice-editing]

For comprehensive changes to an invoice, use the full editing mode which opens the invoice generator with all data pre-filled.

### How to Access Full Edit Mode [#how-to-access-full-edit-mode]

1. Navigate to the invoice details page by clicking any invoice from the invoices list
2. Click the **Edit** button in the page header
3. The invoice generator opens with all existing data pre-filled

<DocImage src="https://storage.pinebill.app/public/docs/image/INV-26-21-YLWTBGXG-PineBill-01-23-2026_12_00_PM.webp" alt="Edit button location on invoice details page header" maxHeight="400px" className="w-full p-0" />

### Editing in the Generator [#editing-in-the-generator]

The invoice generator in edit mode works identically to creating a new invoice, but with all fields already populated:

* **Products/Services** - Add, remove, or modify line items
* **Customer** - Change the customer (if needed)
* **Invoice Details** - Update dates, numbers, currency, and custom fields
* **Payment Methods** - Add or remove payment options
* **Company Information** - Adjust company details for this invoice

<DocImage src="https://storage.pinebill.app/public/docs/image/Create-Invoice-PineBill-01-23-2026_12_02_PM.webp" alt="Invoice generator in edit mode with pre-filled data" maxHeight="500px" className="w-full p-0" />

### Saving Changes [#saving-changes]

1. Make your desired changes across any of the tabs
2. Click the **Save Changes** button (top right)
3. The PDF is regenerated with the updated information
4. You're redirected back to the invoice details page

<Callout type="warn">
  Editing an invoice regenerates the PDF. If you've already shared the invoice, the shared link will
  show the updated version.
</Callout>

***

## Quick Edits on Details Page [#quick-edits-on-details-page]

For minor updates, you can edit certain fields directly on the invoice details page without opening the full generator.

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoices-List-PineBill-11-30-2025_10_08_PM.png" alt="Quick edit options: status badge, description pencil icon, and paid date picker" maxHeight="400px" className="w-full p-0" />

### Editable Fields [#editable-fields]

| Field           | How to Edit                                  | Notes                                       |
| --------------- | -------------------------------------------- | ------------------------------------------- |
| **Status**      | Click the status badge to open dropdown menu | Changes saved immediately                   |
| **Description** | Click the pencil icon next to description    | Opens text editor, save or cancel changes   |
| **Paid Date**   | Click the pencil icon next to paid date      | Opens date picker, must be after issue date |

### Status Updates [#status-updates]

Click the status badge to instantly change the invoice status:

1. Click on the current status (e.g., "DRAFT")
2. Select the new status from the dropdown
3. Change is saved immediately

Available statuses: Draft, Sent, Paid, Overdue, Cancelled

### Description Editing [#description-editing]

1. Click the pencil icon next to the description field
2. Type or modify the description text
3. Click **Save** to apply changes or **Cancel** to discard

### Paid Date [#paid-date]

1. Click the pencil icon next to the paid date
2. Select a date from the date picker
3. The date must be on or after the invoice issue date
4. Changes save automatically when you select a date

***

## Employee Assignment [#employee-assignment]

You can assign or change the employee responsible for an invoice directly from the details page.

### Assigning an Employee [#assigning-an-employee]

1. Scroll to the "Assigned Employee" section
2. Click **Assign Employee**
3. Select a team member from the dropdown
4. Assignment is saved immediately

<DocImage src="https://storage.pinebill.app/public/docs/image/Annotate-Image-01-23-2026_12_07_PM.webp" alt="Assign Employee section on invoice details page" maxHeight="400px" className="w-full p-0" />

### Changing or Removing Assignment [#changing-or-removing-assignment]

* Click **Change** to select a different employee
* Click **Unassign** to remove the current assignment

Employee assignments help track performance metrics and sales attribution.

***

## Related Topics [#related-topics]

* [Invoice Details Page](/docs/invoices/invoice-details) - View and manage invoice information
* [Invoice Statuses](/docs/invoices/invoice-statuses) - Understanding the invoice lifecycle
* [Creating Invoices](/docs/invoices/creating-invoices) - Step-by-step invoice creation guide


# Invoice Management (/docs/invoices)







## Invoice Management Overview [#invoice-management-overview]

Invoices are at the heart of PineBill. Whether you're billing clients for products, services, or hourly work, PineBill provides powerful yet intuitive invoice management tools. This section covers everything from invoice creation to status tracking and sharing.

## Invoice Lifecycle [#invoice-lifecycle]

Understanding how invoices flow through your business:

```
Draft → Sent → Paid
         ↓
      Overdue (if past due date)
```

Any status can also move to:

```
→ Cancelled
```

\[Diagram: Invoice lifecycle flow showing status transitions with arrows]

**Status Meanings:**

| Status        | Description                            | Next Actions                   |
| ------------- | -------------------------------------- | ------------------------------ |
| **Draft**     | Created but not sent to customer       | Edit, send, or delete          |
| **Sent**      | Shared with customer, awaiting payment | Mark as paid, send reminder    |
| **Paid**      | Payment received and recorded          | Archive, export for accounting |
| **Overdue**   | Past due date without payment          | Send reminder, follow up       |
| **Cancelled** | Invoice voided or cancelled            | Archive or delete              |

Learn more about [Invoice Statuses](/docs/invoices/invoice-statuses).

## Invoice Modes [#invoice-modes]

PineBill supports two invoicing modes to match your business model:

<Tabs items="['Product', 'Hourly']">
  <Tab value="Product">
    ### Product Mode (Default) [#product-mode-default]

    For businesses that sell products or deliver discrete services:

    **Characteristics:**

    * Line items with quantity and unit price
    * Subtotal calculated as: quantity × price
    * Ideal for: retail, wholesale, project-based work, one-time services

    **Example:**

    ```
    Website Design Service    1 × $2,500 = $2,500
    Logo Design              1 × $500   = $500
    -------------------------------------------
    Subtotal:                            $3,000
    ```
  </Tab>

  <Tab value="Hourly">
    ### Hourly Mode [#hourly-mode]

    For businesses that bill by time:

    **Characteristics:**

    * Time-based line items
    * Hours/minutes tracking
    * Hourly rate pricing
    * Ideal for: consultants, freelancers, legal services, agencies

    **Example:**

    ```
    Senior Developer    40 hrs × $150/hr = $6,000
    Junior Developer    20 hrs × $75/hr  = $1,500
    -------------------------------------------
    Subtotal:                            $7,500
    ```
  </Tab>
</Tabs>

<Callout type="tip">
  Choose the mode that matches how you charge clients. You can use different modes for different
  invoices within the same organization.
</Callout>

## Key Features [#key-features]

Explore powerful invoice management features:

<Cards>
  <Card title="Creating Invoices" description="Master the invoice generator with step-by-step guidance for all options" href="/docs/invoices/creating-invoices" />

  <Card title="Invoice Components" description="Understand all sections and elements that make up an invoice" href="/docs/invoices/invoice-components" />

  <Card title="Invoice Templates" description="Choose and customize professional invoice designs" href="/docs/invoices/invoice-templates" />

  <Card title="Invoice Statuses" description="Track your invoices through their lifecycle" href="/docs/invoices/invoice-statuses" />

  <Card title="Editing Invoices" description="Modify existing invoices and understand best practices" href="/docs/invoices/editing-invoices" />

  <Card title="Sharing Invoices" description="Securely share invoices with password protection and expiration" href="/docs/invoices/sharing-invoices" />

  <Card title="Invoice Settings" description="Configure invoice numbers, defaults, and preferences" href="/docs/invoices/invoice-settings" />
</Cards>

## Invoice List and Filtering [#invoice-list-and-filtering]

Access and manage all your invoices with powerful search, sorting, and filtering capabilities. Learn how to efficiently navigate your invoice list and find exactly what you need.

[Learn more about Invoice List and Filtering →](/docs/invoices/invoice-list)

## Invoice Statuses [#invoice-statuses]

Understanding invoice status codes is crucial for managing your invoicing workflow. Learn about the five status types (DRAFT, SENT, PAID, OVERDUE, CANCELLED), their automatic behaviors, and common status transitions.

[Learn more about Invoice Statuses →](/docs/invoices/invoice-statuses)

## Common Use Cases [#common-use-cases]

Discover real-world examples and best practices for different business types including freelance consultants, e-commerce businesses, agencies, subscription services, and professional services.

[Learn more about Common Invoice Use Cases →](/docs/invoices/invoice-use-cases)

## Troubleshooting [#troubleshooting]

<Accordions type="single">
  <Accordion title="Can't Create Invoice" id="cant-create-invoice">
    **Problem:** Invoice generator not working.

    **Solutions:**

    * Ensure you've completed organization setup
    * Check you have at least one customer
    * Verify you have products or can add temporary items
    * Clear browser cache and try again
  </Accordion>

  <Accordion title="Invoice Number Conflicts" id="invoice-number-conflicts">
    **Problem:** Duplicate invoice numbers.

    **Solutions:**

    * Check invoice number settings
    * Switch to SECURE\_RANDOM strategy to avoid conflicts
    * Contact support if issue persists
  </Accordion>

  <Accordion title="PDF Won't Generate" id="pdf-wont-generate">
    **Problem:** Error when generating invoice PDF.

    **Solutions:**

    * Verify all required fields are filled
    * Check that customer has a name
    * Ensure at least one line item exists
    * Try a different template
    * Contact support with error message
  </Accordion>
</Accordions>


# Invoice Components (/docs/invoices/invoice-components)





## Invoice Components [#invoice-components]

Every PineBill invoice is carefully structured to include all the essential information needed for professional billing. Understanding these components will help you create complete and effective invoices.

## Header Information [#header-information]

The invoice header contains your business identity and key reference details.

**Includes:**

* Your company logo and name
* Your business address and contact details
* Invoice title ("INVOICE")
* Invoice number (unique identifier)
* Issued date and due date
* Terms of payment (e.g., Net 30)
* Custom Term Fields (if applicable)

<DocImage src="https://storage.pinebill.app/public/docs/image/invoice-header.webp" alt="First Invoice Screenshot" maxHeight="440px" className="w-full p-0" />

## Customer Information [#customer-information]

The "Issued To" section identifies who is being invoiced.

**Includes:**

* "Issued To:" section label
* Customer name
* Customer ID
* Customer address
* Customer contact details (email, phone)

<DocImage src="https://storage.pinebill.app/public/docs/image/invoice-customer-section.png" alt="First Invoice Screenshot" maxHeight="440px" className="w-full p-0" />

## Line Items Table [#line-items-table]

The core of your invoice where you itemize products or services.

**Includes:**

* Item descriptions
* Model/SKU numbers (if applicable)
* Quantities
* Unit prices
* Line totals (calculated automatically)

**For Product Mode:**

* Standard quantity × price calculations

**For Hourly Mode:**

* Hours/minutes worked
* Hourly rate
* Time-based totals

<DocImage src="https://storage.pinebill.app/public/docs/image/invoice-products-section1.webp" alt="First Invoice Screenshot" maxHeight="440px" className="w-full p-0" />

## Calculations Section [#calculations-section]

Shows the financial breakdown from subtotal to final amount due.

**Includes:**

* **Subtotal** - Sum of all line items
* **Discount** - Percentage or fixed amount reduction (if applied)
* **Tax** - Calculated tax amount (if applicable)
* **Shipping/Delivery Fee** - Additional charges (if applicable)
* **Grand Total** - Final amount due (prominently displayed)

<DocImage src="https://storage.pinebill.app/public/docs/image/invoice-subtotals.png" alt="First Invoice Screenshot" maxHeight="440px" className="w-full p-0" />

## Payment Information [#payment-information]

Provides customers with clear payment instructions.

**Includes:**

* Payment method details (bank account, PayPal, Crypto wallet, or any custom method(Stripe, Square, etc.)) (Optional)

<DocImage src="https://storage.pinebill.app/public/docs/image/invoice-payments-section.png" alt="First Invoice Screenshot" maxHeight="440px" className="w-full p-0" />

## Footer [#footer]

Additional information and notes appear at the bottom of the invoice.

**Includes:**

* Additional notes or custom messages (Optional)
* Digital signature (optional)

<DocImage src="https://storage.pinebill.app/public/docs/image/invoice-footer-section.webp" alt="First Invoice Screenshot" maxHeight="440px" className="w-full p-0" />

## Full Invoice Example [#full-invoice-example]

Here's how all components come together in a complete invoice:

<DocImage src="https://storage.pinebill.app/public/docs/image/invoice-sample-image.webp" alt="First Invoice Screenshot" maxHeight="500px" className="w-full p-0" />

## Component Customization [#component-customization]

Different invoice templates may arrange these components differently, but all essential information is always included. Learn more about customizing the appearance in [Invoice Templates](/docs/invoices/invoice-templates).

## Related Topics [#related-topics]

* [Creating Invoices](/docs/invoices/creating-invoices) - Learn how to fill in each component
* [Invoice Templates](/docs/invoices/invoice-templates) - Choose different visual layouts
* [Invoice Settings](/docs/invoices/invoice-settings) - Configure default values for components


# Invoice Details Page (/docs/invoices/invoice-details)





## Overview [#overview]

The Invoice Details page displays all information about a specific invoice. Access it by clicking any invoice from the invoices list. The page is divided into two main sections: the left column contains invoice details, items, and customer information, while the right sidebar shows the total amount, PDF actions, and timeline.

<DocImage src="https://storage.pinebill.app/public/docs/image/INV-26-21-YLWTBGXG-PineBill-01-23-2026_12_05_PM.webp" alt="Invoice Details Page Overview" maxHeight="500px" className="w-full p-0" />

***

## Page Header [#page-header]

At the top of the page, you'll find the invoice number and quick action buttons:

* **Back Button** - Returns you to the invoices list
* **[Edit](/docs/invoices/editing-invoices)** - Open the invoice in the generator for full editing (not available for cancelled invoices)
* **View PDF** (Mobile/Tablet only) - Opens the PDF viewer in a modal
* **[Manage Shares](/docs/invoices/invoice-sharing)** - View and manage all shared links for this invoice
* **[Share PDF](/docs/invoices/invoice-sharing)** - Create a new shareable link with customizable expiration
* **Delete** - Permanently delete the invoice (owners only)

<DocImage src="https://storage.pinebill.app/public/docs/image/INV-26-21-YLWTBGXG-PineBill-01-23-2026_12_06_PM.webp" alt="Invoice Details Page Overview" maxHeight="500px" className="w-full p-0" />

***

## Invoice Details [#invoice-details]

The invoice details section shows core information about your invoice. Some fields are editable directly from this page using quick inline edits. For comprehensive changes (items, customer, payment methods, etc.), use the **Edit** button in the header to open the full invoice generator. See [Editing Invoices](/docs/invoices/editing-invoices) for more details.

### Editable Fields [#editable-fields]

| Field           | How to Edit                                 | Notes                                                                     |
| --------------- | ------------------------------------------- | ------------------------------------------------------------------------- |
| **Status**      | Click the status badge to open popover menu | Changes saved immediately. Options: Draft, Sent, Paid, Overdue, Cancelled |
| **Description** | Click edit icon to open text editor         | Add or modify invoice notes. Save or cancel changes                       |
| **Paid Date**   | Click edit icon to open date picker         | Cannot be before issued date or in the future                             |

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoices-List-PineBill-11-30-2025_10_08_PM.png" alt="Invoice Details Editable Fields" maxHeight="500px" className="w-full p-0" />

### Read-Only Information [#read-only-information]

* **Invoice Number** - Unique identifier generated when the invoice was created
* **Issued Date** - When the invoice was originally created
* **Due Date** - Payment deadline (if specified)
* **Exchange Rate** - Shows currency conversion rate and capture date for non-USD invoices, this value is not the real-time rate but the rate at creation time of the invoice.

***

## Invoice Summary [#invoice-summary]

This section displays all line items and the calculation breakdown.

### Items List [#items-list]

Each item shows:

* Product or service name
* Model or SKU (if applicable)
* Unit price
* Quantity
* Line total (price × quantity)

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoices-List-PineBill-11-30-2025_10_14_PM.png" alt="Invoice Details Tab" maxHeight="400px" className="w-full p-0" />

### Calculations [#calculations]

Below the items table, you'll see the complete calculation:

1. **Subtotal** - Sum of all line items
2. **Shipping** - Delivery or shipping costs (if applicable)
3. **Discount** - Applied discount amount (displayed in green)
4. **Tax** - Tax amount with rate shown as percentage or fixed amount
   * Tax included invoices show "(included)" next to the tax rate
   * Example: "Tax (5%)" or "Tax ($10.00)"
5. **Total** - Final amount due

If there's a discrepancy between the calculated total and stored amount, a warning will appear highlighting the difference.

***

## Customer Information [#customer-information]

View complete customer details including:

* Full name
* Email address
* Phone number
* Complete billing address with zip code

This information is pulled from the customer record and cannot be edited directly from the invoice. To update customer details, go to the [Editing Customers](/docs/customers/editing-customer) section. Updating the customer record will reflect changes on the future invoices.

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoices-List-PineBill-11-30-2025_10_18_PM.png" alt="Invoice Details Customer Information" maxHeight="400px" className="w-full p-0" />

***

## Assigned Employee [#assigned-employee]

Track which team member is responsible for this invoice. This is useful for analyzing employee performance and tracking sales.

### When No Employee is Assigned [#when-no-employee-is-assigned]

You'll see a placeholder with an "Assign Employee" button. Click it to open the employee selector and choose from your team members.

### When Employee is Assigned [#when-employee-is-assigned]

The card displays:

* Employee name
* Employee ID
* Email and phone (if available)
* Position and department (if specified)

You can **Change** the assigned employee or **Unassign** to remove the employee from this invoice.

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoices-List-PineBill-11-30-2025_10_21_PM.png" alt="Invoice Details Customer Information" maxHeight="400px" className="w-full" />

***

## Custom Fields [#custom-fields]

If the invoice includes custom fields, they appear in the "Additional Information" section. These are custom label-value pairs you added when creating the invoice, such as:

* Purchase Order Number
* Project ID
* Reference Number
* Any other custom data

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoices-List-PineBill-12-01-2025_08_39_AM.png" alt="Invoice Details Customer Information" maxHeight="400px" className="w-full" />

***

## Payment Methods [#payment-methods]

View all payment options available for this invoice. Each payment method displays relevant details:

**Bank Transfer**
Shows bank name, branch, address, account details, IBAN, SWIFT code, routing number, and sort code (depending on what was configured).

**PayPal**
Displays the PayPal email address.

**Cryptocurrency**
Shows the wallet address and currency type.

**Custom Payment Methods**
Displays custom payment method name and any custom fields defined.

***

## Terms & Notes [#terms--notes]

This section displays:

* **Terms of Payment** - Payment conditions and deadlines (e.g., "Net 30", "Due within 14 days")
* **Additional Notes** - Custom end message or notes included on the invoice

***

## Right Sidebar [#right-sidebar]

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoices-List-PineBill-12-01-2025_08_42_AM.png" alt="Invoice Details Customer Information" maxHeight="400px" className="w-full p-0" />

### Total Amount [#total-amount]

The total amount is prominently displayed at the top of the sidebar, showing:

* Primary amount in the invoice currency
* Converted amount (if currency is not USD)
* Currency code

### PDF Document [#pdf-document]

Click **View PDF** to open the invoice PDF in a viewer modal where you can:

* Preview the PDF
* Download the PDF to your device
* Print the invoice

### Timeline [#timeline]

The timeline tracks important dates and events:

* **Created** - When the invoice was first generated, with precise timestamp
* **Last Updated** - Most recent modification date and time
* **Paid** - Payment received date (if applicable)
  * Click the edit icon to modify the paid date
  * Color-coded indicator shows payment status

Each event includes both date and time for complete tracking.

***

## Tips & Best Practices [#tips--best-practices]

**Quick Edits**
Use the inline edit icons to quickly update paid dates, descriptions, and status without leaving the page.

**Status Management**
Click the status badge for instant status updates. The popover menu provides one-click access to all status options.

**Sharing & Security**
Use "Manage Shares" to track who has access to the invoice. You can revoke access at any time by deleting shared links.

**Employee Performance**
Assign employees to invoices to later analyze performance metrics and track which team members generated the most revenue.

**Custom Fields**
Use custom fields to add any additional information needed for your business process or compliance requirements.

***

## Related Topics [#related-topics]

* [Editing Invoices](/docs/invoices/editing-invoices) - Full and quick editing options
* [Creating Invoices](/docs/invoices/creating-invoices) - Step-by-step guide to creating invoices
* [Invoice Statuses](/docs/invoices/invoice-statuses) - Understanding the invoice lifecycle
* [Invoice List](/docs/invoices/invoice-list) - Managing multiple invoices


# Invoices List (/docs/invoices/invoice-list)





## Invoices List and Filtering [#invoices-list-and-filtering]

Access all your invoices from the Invoices page with powerful search and filtering capabilities.

## List View Features [#list-view-features]

### Table Columns [#table-columns]

| Column        | Description                                       |
| ------------- | ------------------------------------------------- |
| Checkbox      | Select invoice for bulk actions (owners only)     |
| Invoice #     | Unique invoice identifier                         |
| Customer Name | Name of the customer                              |
| Amount        | Total amount with currency                        |
| Status        | Current status (color-coded pill)                 |
| Issue Date    | When invoice was created                          |
| Due Date      | Payment deadline                                  |
| Assigned To   | Employee assignment (if applicable)               |
| Actions       | Quick actions (view, edit, change status, delete) |

### Sorting Options [#sorting-options]

| Feature        | Description                         |
| -------------- | ----------------------------------- |
| Column Sort    | Click any column header to sort     |
| Sort Direction | Toggle between ascending/descending |
| Default Sort   | Newest first (by creation date)     |

### Pagination Controls [#pagination-controls]

| Option         | Description                          |
| -------------- | ------------------------------------ |
| Items per Page | 10, 25, 50, or 100 invoices per page |
| Navigation     | Previous/Next buttons                |
| Page Jump      | Jump to specific page number         |

<DocImage src="https://storage.pinebill.app/public/docs/image/invoices-list-thumb1.png" alt="First Invoice Screenshot" maxHeight="440px" className="w-full p-0" />

## Search and Filtering [#search-and-filtering]

Find invoices quickly with powerful filters:

### Search Bar [#search-bar]

| Search Type      | Description                      |
| ---------------- | -------------------------------- |
| Invoice Number   | Search by unique invoice ID      |
| Customer Name    | Search by customer name          |
| Customer Email   | Search by customer email address |
| Description      | Search in invoice description    |
| Real-time Search | Results update as you type       |

### Status Filter [#status-filter]

| Feature            | Options                                 |
| ------------------ | --------------------------------------- |
| Available Statuses | Draft, Sent, Paid, Overdue, Cancelled   |
| Selection Type     | Multi-select to show multiple statuses  |
| Filter Display     | Active filters shown as removable chips |

### Date Range Filter [#date-range-filter]

| Filter Type   | Options                                            |
| ------------- | -------------------------------------------------- |
| Range Type    | Filter by issued date range                        |
| Quick Presets | Last 7 days, Last 30 days, Last 90 days, This Year |
| Custom Range  | Custom date range picker                           |

### Employee Filter [#employee-filter]

| Feature            | Description                                 |
| ------------------ | ------------------------------------------- |
| Filter by Employee | Show invoices assigned to specific employee |
| Unassigned         | Show invoices without employee assignment   |
| Use Case           | Useful for team organizations               |

### Active Filters Management [#active-filters-management]

| Feature       | Description                    |
| ------------- | ------------------------------ |
| Display       | Shown as chips above the table |
| Remove Filter | Click X on any chip to remove  |
| Clear All     | Reset all filters at once      |

<DocImage src="https://storage.pinebill.app/public/docs/image/docs-invoices-list-filters.png" alt="First Invoice Screenshot" maxHeight="440px" className="w-full p-0" />

## Bulk Actions [#bulk-actions]

Select multiple invoices to perform batch operations, saving time when managing large numbers of invoices.

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoices-List-PineBill-01-25-2026_02_29_PM.webp" alt="First Invoice Screenshot" maxHeight="440px" className="w-full p-0" />

### Selecting Invoices [#selecting-invoices]

| Feature             | Description                                                             |
| ------------------- | ----------------------------------------------------------------------- |
| Checkbox Column     | Click the checkbox next to any invoice to select it                     |
| Select All          | Use the header checkbox to select all invoices on the current page      |
| Indeterminate State | Header checkbox shows a minus icon when some (but not all) are selected |
| Selection Count     | Shows how many invoices are currently selected                          |

### Available Bulk Actions [#available-bulk-actions]

When you have invoices selected, a bulk actions bar appears with the following options:

| Action          | Description                                        |
| --------------- | -------------------------------------------------- |
| Change Status   | Update the status of all selected invoices at once |
| Delete Selected | Remove all selected invoices (with confirmation)   |
| Clear Selection | Deselect all invoices                              |

### Bulk Status Change [#bulk-status-change]

Change the status of multiple invoices simultaneously:

1. Select the invoices you want to update
2. Click **Change Status** in the bulk actions bar
3. Choose the new status from the dropdown (Draft, Sent, Paid, Overdue, or Cancelled)
4. Confirm the change in the dialog

<Callout type="info">
  When changing status to **Paid**, the paid date is automatically set. When changing from Paid to
  another status, the paid date is cleared.
</Callout>

### Bulk Delete [#bulk-delete]

Remove multiple invoices at once:

1. Select the invoices you want to delete
2. Click **Delete Selected**
3. Review the confirmation dialog showing the number of invoices to be deleted
4. Confirm to permanently remove the selected invoices

<Callout type="warning">
  Bulk delete is permanent and cannot be undone. All associated data including PDFs will be removed.
</Callout>

<Callout type="note">
  Bulk actions are only available to organization owners.
</Callout>

## Exporting Invoices [#exporting-invoices]

Download invoices as a single ZIP file containing every invoice PDF and an Excel spreadsheet — useful for sharing with your accountant, archiving, or reconciling payments.

### How to Export [#how-to-export]

1. Open the **Invoices** page and apply any search, filters, or sorting you need
2. Optionally select specific invoices using the checkboxes
3. Click **Export** in the table toolbar (next to **Columns**)
4. Wait for the progress notification to finish — the ZIP downloads automatically

| Selection              | What gets exported                                                                |
| ---------------------- | --------------------------------------------------------------------------------- |
| No invoices selected   | All invoices on the current page are selected and exported                        |
| Some invoices selected | Only the selected invoices — the button shows the count, e.g. &#x2A;*Export (5)** |

<Callout type="info">
  Export works on the current page. To export more invoices at once, increase **Items per Page** (up
  to 100), or export each page one after another.
</Callout>

<DocImage src="https://storage.pinebill.app/public/changelogs/images/06e98e73-be44-4b5a-be32-bdd08827e96c.png" alt="Export button on the Invoices list with 10 invoices selected" maxHeight="400px" className="w-full p-0" />

### What's in the ZIP [#whats-in-the-zip]

| File                        | Contents                                                             |
| --------------------------- | -------------------------------------------------------------------- |
| `invoices.xlsx`             | Excel workbook with an **Invoices** sheet and a **Line Items** sheet |
| `pdfs/invoice-<number>.pdf` | The PDF of each exported invoice                                     |

**Invoices sheet** — one row per invoice:

| Column group | Columns                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------- |
| Invoice      | Invoice #, Status, Description, Created At                                                     |
| Customer     | Customer, Customer Email, Customer Phone, Customer Address, Zip Code, Country, Customer Tax ID |
| Dates        | Issued Date, Due Date, Paid Date                                                               |
| Amounts      | Currency, Subtotal, Discount, Tax Rate, Tax Type, Tax Included, Shipping, Total                |
| Other        | Items (count), Project, Assigned To, PDF File                                                  |

**Line Items sheet** — one row per invoice item: Invoice #, Customer, Item, Model, Description, Quantity, Unit Price, Line Total, and Currency.

Dates and amounts are stored as real spreadsheet values, so you can sort, filter, and sum them immediately. The header row is frozen and column filters are enabled.

### File Names [#file-names]

Each export gets a unique name so multiple downloads never overwrite each other:

```
invoices_2026-09-14_1.zip
invoices_2026-09-14_2.zip
invoices_2026-09-14_3.zip
```

The number increases with every export on the same day and restarts the next day.

<Callout type="warning">
  If an invoice has no generated PDF (or it can't be downloaded), the export still completes. A
  notification lists the affected invoice numbers, and their **PDF File** column in the spreadsheet
  shows "Not available".
</Callout>

<Callout type="note">
  Export is available to all organization members who can view invoices — not only owners.
</Callout>

## Tips for Efficient Search [#tips-for-efficient-search]

<Callout type="tip">
  Use the search bar for quick lookups by customer or invoice number. Combine multiple filters to
  narrow down results when managing large invoice lists.
</Callout>

* Combine multiple filters for precise results
* Use status filters to focus on actionable invoices (e.g., Overdue)
* Save time with date presets for common reports
* Use bulk actions to update multiple invoices at once
* Filter first, then click **Export** to download exactly the invoices you need
* Clear all filters to start fresh


# Invoice Reminders (/docs/invoices/invoice-reminders)





## 1. Overview [#1-overview]

Invoice reminders help you follow up with customers before and after an invoice is due. After reminders are enabled, PineBill schedules email reminders for the invoice and records reminder activity in the invoice email history.

<DocImage src="https://storage.pinebill.app/public/docs/image/INV-April-JGPZHGLN-PineBill-04-24-2026_08_53_AM.png" alt="Invoice Reminders Screenshot" maxHeight="440px" className="w-full p-0" />

## 2. When Reminders Can Be Used [#2-when-reminders-can-be-used]

You can enable reminders when the invoice:

* Has a due date
* Is not marked as paid
* Is not cancelled
* Has at least one reminder recipient

If the invoice is paid or cancelled later, pending reminders are cancelled automatically.

## 3. Reminder Schedule [#3-reminder-schedule]

PineBill uses a fixed three-step schedule:

| Reminder   | When it sends              |
| ---------- | -------------------------- |
| Before due | 7 days before the due date |
| Due today  | On the due date            |
| Overdue    | 7 days after the due date  |

You choose the send time and timezone. PineBill only schedules reminder dates that are still in the future.

## 4. Enable Invoice Reminders [#4-enable-invoice-reminders]

1. Open **Invoices**.
2. Select the invoice you want to follow up on.
3. Find the **Email Reminders** card on the invoice details page.
4. Turn on the reminder switch.
5. Expand the card if it is not already open.

<DocImage src="https://storage.pinebill.app/public/docs/image/INV-April-JGPZHGLN-PineBill-04-24-2026_08_53_AM.png" alt="Invoice Reminders Screenshot" maxHeight="440px" className="w-full p-0" />

## 5. Add Recipients [#5-add-recipients]

Add the email addresses that should receive reminder emails.

* The customer email is used as the default recipient when available.
* You can add up to 5 recipients.
* Duplicate email addresses are ignored.
* At least one recipient is required before reminders can be saved.

<DocImage src="https://storage.pinebill.app/public/docs/image/INV-April-JGPZHGLN-PineBill-04-24-2026_08_54_AM.png" alt="Invoice Reminders Screenshot" maxHeight="440px" className="w-full p-0" />

## 6. Set Send Time and Timezone [#6-set-send-time-and-timezone]

Choose when reminders should be sent:

1. Select the hour.
2. Select the minute.
3. Choose the timezone.

Use the customer's timezone when possible. This keeps reminders from arriving too early or too late in their local day.

## 7. Attach the Invoice PDF [#7-attach-the-invoice-pdf]

Turn on **Attach invoice PDF** if you want each reminder email to include the invoice PDF.

This option is only available when the invoice already has a generated PDF. If the invoice PDF is missing, generate or update the invoice PDF first, then return to the reminder settings.

## 8. Save Reminders [#8-save-reminders]

Click **Save Reminders** after recipients, send time, and timezone are set.

The schedule preview shows each reminder and its current status:

| Status        | Meaning                                          |
| ------------- | ------------------------------------------------ |
| Scheduled     | The reminder is waiting to be sent               |
| Sending       | PineBill is currently processing it              |
| Sent          | The reminder email was sent                      |
| Skipped       | PineBill skipped it because it no longer applies |
| Failed        | PineBill could not send it                       |
| Cancelled     | The reminder was cancelled                       |
| Not scheduled | No active reminder exists for that step          |

## 9. Disable Reminders [#9-disable-reminders]

To stop future reminders:

1. Open the invoice.
2. Expand **Email Reminders**.
3. Click **Disable**.

Disabling reminders cancels pending reminders. Reminders that were already sent remain in the email history.

## 10. Track Reminder Emails [#10-track-reminder-emails]

Reminder emails appear in the invoice **Email History** section. Use it to confirm:

* Which reminder was sent
* The recipient email address
* When it was sent
* Whether the invoice link was clicked

## 11. Common Issues [#11-common-issues]

**The reminder switch is disabled**

Add a due date to the invoice. Reminders are also unavailable for paid and cancelled invoices.

**The PDF attachment option is disabled**

The invoice does not have a generated PDF yet. Generate or update the invoice PDF before attaching it to reminders.

**No reminders were scheduled**

All reminder dates may already be in the past. Update the invoice due date or send the customer a manual email instead.

**A reminder was skipped**

This usually means the invoice was paid, cancelled, disabled, missing a due date, or no longer has valid reminder recipients.

## 12. Related Topics [#12-related-topics]

* [Invoice Details Page](/docs/invoices/invoice-details)
* [Invoice Sharing](/docs/invoices/invoice-sharing)
* [Invoice Statuses](/docs/invoices/invoice-statuses)


# Invoice Settings (/docs/invoices/invoice-settings)







## Overview [#overview]

Invoice Settings let you control how invoice numbers are generated and set default content for new invoices. This saves time and ensures consistency across all your invoices.

<Callout type="info">
  Only organization owners can edit invoice settings.
</Callout>

## Accessing Invoice Settings [#accessing-invoice-settings]

Open invoice settings from the centralized settings hub:

1. Open &#x2A;*[Settings](/dashboard/setup)**
2. In **Documents*&#x2A;, click &#x2A;*[Invoice Settings](/dashboard/invoice-settings)**
3. Click the **Edit Settings** button (owners only)

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-04-15-2026_04_38_PM.png" alt="Invoice Settings Page Overview" maxHeight="350px" className="w-[95%] p-0" />

***

## Invoice Number Generation [#invoice-number-generation]

Control how invoice numbers are automatically created for each new invoice.

### Generation Strategy [#generation-strategy]

Choose how your invoice numbers will be formatted:

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoice-Settings-PineBill-12-01-2025_09_34_AM.png" alt="Invoice Settings Page Overview" maxHeight="350px" className="w-[95%] p-0" />

| Strategy           | Description                                          | Example                                  | Best For                                                                  |
| ------------------ | ---------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------- |
| **Sequential**     | Creates numbered invoices in order                   | `INV-2025-0001`, `INV-2025-0002`         | Small businesses, simple numbering, easy customer reference               |
| **Secure Random**  | Generates random alphanumeric codes                  | `INV-2025-A7K9M2`, `INV-2025-X3F8P1`     | Enhanced security, preventing number guessing, high-volume businesses     |
| **Timestamp**      | Uses date and time                                   | `INV-20250910-X4Y7`, `INV-20250910-P9K2` | Date-based organization, chronological sorting, time tracking             |
| **Custom Pattern** | Create your own format using placeholders (advanced) | `{prefix}-{quarter}-{seq:4}`             | Complex requirements, multi-department systems, specific compliance needs |

### Prefix [#prefix]

Set the prefix that appears at the start of all invoice numbers.

**Requirements:**

* 3-10 characters
* Examples: `INV`, `BILL`, `ORG`

### Sequence Length [#sequence-length]

Control how many digits appear in sequential numbers.

**Settings:**

* Minimum: 4 digits
* Maximum: 10 digits
* Example: Length 4 = `0001`, Length 6 = `000001`

<Callout type="tip">
  Use longer sequences if you create many invoices per year.
</Callout>

### Custom Pattern (Advanced) [#custom-pattern-advanced]

Create complex invoice numbers with placeholders.

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoice-Settings-PineBill-12-01-2025_09_46_AM.png" alt="Invoice Settings Page Overview" maxHeight="350px" className="w-[95%] p-0" />

**Available Invoice Numbering Pattern:**

<div className="overflow-x-auto whitespace-nowrap">
  | Category              | Placeholder       | Description                           | Example               |
  | --------------------- | ----------------- | ------------------------------------- | --------------------- |
  | **Organization**      | `{prefix}`        | Your organization prefix              | `INV`                 |
  |                       | `{org}`           | First 3 characters of organization ID | `ABC`                 |
  | **Date & Time**       | `{year}`          | Current year (4 digits)               | `2025`                |
  |                       | `{year2}`         | Short year (2 digits)                 | `25`                  |
  |                       | `{month}`         | Month number                          | `01-12`               |
  |                       | `{day}`           | Day of month                          | `01-31`               |
  |                       | `{quarter}`       | Quarter                               | `Q1-Q4`               |
  |                       | `{week}`          | Week number                           | `01-53`               |
  |                       | `{monthName}`     | Short month name                      | `Jan, Feb`            |
  |                       | `{monthNameFull}` | Full month name                       | `January`             |
  |                       | `{dayOfWeek}`     | Day name                              | `Mon, Tue`            |
  |                       | `{timestamp}`     | YYYYMMDD format                       | `20250101`            |
  | **Counters & Random** | `{seq:N}`         | Sequential number with N digits       | `{seq:4}` → `0001`    |
  |                       | `{random:N}`      | Random string of N characters         | `{random:4}` → `X7K9` |
  |                       | `{uuid:N}`        | First N characters of UUID            | `{uuid:6}` → `A3F8B2` |
  |                       | `{hex:N}`         | Random hex string                     | `{hex:4}` → `9A2F`    |
</div>

**Examples:**

| Pattern                                 | Result               |
| --------------------------------------- | -------------------- |
| `{prefix}-{year}-{seq:4}`               | `INV-2025-0001`      |
| `{org}-{quarter}-{random:4}`            | `ABC-Q1-X7K9`        |
| `{monthName}{day}-{uuid:6}`             | `Jan15-A3F8B2`       |
| `{prefix}-{year2}{month}-{seq:5}`       | `INV-2501-00001`     |
| `{prefix}-{timestamp}-{hex:4}`          | `BILL-20250101-9A2F` |
| `{org}-{year}-{quarter}-{seq:3}`        | `ABC-2025-Q1-001`    |
| `{prefix}{monthName}{year2}-{random:6}` | `INVJan25-X7K9M2`    |
| `{year}{month}{day}-{seq:4}`            | `20250115-0001`      |
| `{prefix}-W{week}-{year2}-{random:4}`   | `INV-W03-25-P9K2`    |
| `{dayOfWeek}{monthName}{day}-{uuid:8}`  | `MonJan15-A3F8B2C7`  |

<Callout type="warning">
  Changing invoice number settings doesn't affect existing invoices, only new ones.
</Callout>

***

## Default Invoice Content [#default-invoice-content]

Set default values that automatically fill in when creating new invoices.

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoice-Settings-PineBill-12-01-2025_09_53_AM.png" alt="Invoice Settings Page Overview" maxHeight="400px" className="w-full p-0" />

### Default Terms of Payment [#default-terms-of-payment]

Standard payment terms that appear on all new invoices.

**Examples:**

* "Payment due within 30 days"
* "30% advance, 70% before shipment"
* "Net 15 days from invoice date"

### Default End Message [#default-end-message]

A closing message that appears at the bottom of invoices.

**Examples:**

* "Thank you for your business!"
* "We appreciate your partnership"
* "Please contact us with any questions"

### Default Date Format [#default-date-format]

Choose how dates appear on your invoices.

**Available Formats:**

| Format         | Example           |
| -------------- | ----------------- |
| Month DD, YYYY | December 01, 2025 |
| DD/MM/YYYY     | 01/12/2025        |
| MM/DD/YYYY     | 12/01/2025        |
| DD-MM-YYYY     | 01-12-2025        |
| YYYY-MM-DD     | 2025-12-01        |

### Default Currency Format [#default-currency-format]

Choose how currency values appear on new invoices by default.

| Format           | Example               |
| ---------------- | --------------------- |
| Symbol           | `$1,234.50`           |
| Localized symbol | `US$1,234.50`         |
| Currency code    | `USD 1,234.50`        |
| Currency name    | `1,234.50 US dollars` |
| Accounting       | `($1,234.50)`         |

This default is used when opening the invoice generator. You can still change
the currency format per invoice while creating or editing it.

### Default Invoice Template [#default-invoice-template]

Select the visual design for your invoices.

**[Available Templates:](/docs/invoices/invoice-templates)**

| Template              | Description                               | Best For                                 |
| --------------------- | ----------------------------------------- | ---------------------------------------- |
| **Standard**          | Balanced default design with clean layout | General business use                     |
| **Bold Professional** | Strong dark header with emphasis          | Corporate clients, professional services |
| **Mono**              | Clean, minimal monospace design           | Tech companies, SaaS, developers         |
| **Startup Modern**    | Modern and sleek contemporary style       | Startups, creative agencies              |

<Callout type="tip">
  Hover over each template to see a preview image.
</Callout>

### Default Invoice Language [#default-invoice-language]

Set the language for invoice PDF labels and text. This controls the language used for section titles, column headers, and other text on generated invoice PDFs.

**PineBill Supported Languages:**

| Language    | Native Name     |
| ----------- | --------------- |
| English     | English         |
| German      | Deutsch         |
| French      | Francais        |
| Spanish     | Espanol         |
| Portuguese  | Portugues       |
| Italian     | Italiano        |
| Arabic      | العربية         |
| Chinese     | 中文              |
| Japanese    | 日本語             |
| Korean      | 한국어             |
| Turkish     | Türkçe          |
| Azerbaijani | Azərbaycan dili |

<Callout type="info">
  The language setting affects PDF labels like "Bill To", "Invoice Date", "Total", etc. Your custom
  content (product names, descriptions, messages) remains unchanged.
</Callout>

### Default Custom Fields [#default-custom-fields]

Add extra fields that automatically appear on new invoices.

**What are custom fields?**
Additional information you want to include on every invoice:

* Purchase Order Number
* Project Reference
* Department Code
* Customer ID
* Contract Number

**How to add:**

1. Click **Add Default Custom Field**
2. Enter the **Label** (field name)
3. Enter the **Value** (default content)
4. Click the X to remove unwanted fields

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoice-Settings-PineBill-12-01-2025_10_47_AM.png" alt="Invoice Settings Page Overview" maxHeight="400px" className="w-full p-0" />

<Callout type="info">
  Custom fields can be edited individually when creating each invoice.
</Callout>

***

## Saving Your Settings [#saving-your-settings]

After making changes:

1. Review all your settings
2. Check the invoice number preview
3. Click **Save Invoice Settings**
4. Wait for the success message

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoice-Settings-PineBill-12-01-2025_10_49_AM.webp" alt="Invoice Settings Page Overview" maxHeight="400px" className="w-full p-0" />

<Callout type="tip">
  Click 

  **Cancel**

   to discard changes and restore previous settings.
</Callout>

***

## Troubleshooting [#troubleshooting]

<Accordions type="single">
  <Accordion title="Can't edit settings" id="cant-edit-settings">
    Only organization owners can edit invoice settings. Contact your organization owner to make changes or request ownership transfer.
  </Accordion>

  <Accordion title="Preview not updating" id="preview-not-updating">
    Make sure you've selected a generation strategy. The preview updates automatically when you change
    prefix, length, or pattern fields.
  </Accordion>

  <Accordion title="Custom pattern not working" id="custom-pattern-error">
    Check that you're using valid placeholders with correct syntax. Example: `{seq:4}` not `{seq4}`. Refer to the placeholder list in the tooltip.
  </Accordion>

  <Accordion title="Settings not saving" id="settings-not-saving">
    Ensure all required fields are filled correctly. Check that prefix is 3-10 characters and sequence
    length is 4-10 digits. Look for error messages.
  </Accordion>

  <Accordion title="Invoice numbers duplicating" id="duplicate-numbers">
    Contact support if you see duplicate invoice numbers. This shouldn't happen with any generation
    strategy.
  </Accordion>

  <Accordion title="Template preview not showing" id="template-preview-missing">
    Hover over the template option in the dropdown. If the preview doesn't appear, try refreshing your
    browser.
  </Accordion>

  <Accordion title="Can't remove custom field" id="cant-remove-field">
    Click the X button next to the custom field, then save your settings. Make sure you're in edit mode.
  </Accordion>
</Accordions>


# Invoice Sharing (/docs/invoices/invoice-sharing)







## How To Share Your Invoices [#how-to-share-your-invoices]

Share your invoices with clients, vendors, or team members using secure links or email. You can create multiple share links for each invoice with different settings, or send invoices directly via email with PDF attachments.

## Sending Invoices via Email [#sending-invoices-via-email]

Send your invoices directly to customers via email with professional templates and PDF attachments.

### How to Send an Invoice by Email [#how-to-send-an-invoice-by-email]

<DocImage src="https://storage.pinebill.app/public/docs/image/INV-2025-6V9VLWTD-PineBill-12-09-2025_02_54_PM.png" alt="Invoice Emailing Overview" maxHeight="350px" className="w-full p-0" />

1. Open the invoice you want to send
2. Click the **Send via Email** button at the top right
3. Enter the recipient's email address (defaults to customer email)
4. Add a custom message (optional, up to 500 characters)
5. Click **Send Email**

<DocImage src="https://storage.pinebill.app/public/docs/image/INV-2025-6V9VLWTD-PineBill-12-09-2025_02_57_PM.webp" alt="Invoice Emailing Overview" maxHeight="350px" className="w-full p-0" />

### What Your Customer Receives [#what-your-customer-receives]

When you send an invoice via email, your customer gets:

* **Professional email** with your company name and invoice details
* **PDF attachment** of the complete invoice
* **Secure link** to view the invoice online
* **Your custom message** (if you added one)
* Invoice number, amount, and due date clearly displayed

<DocImage src="https://storage.pinebill.app/public/docs/image/New-Invoice-from-PineBill-Co-LTD-Invoice-INV-2025-6V9VLWTD2025_04_16_PM.webp" alt="Invoice Details Page Overview" maxHeight="350px" className="w-full p-0" />

### Email Tracking [#email-tracking]

Track engagement with your sent invoices:

* See when emails were sent and by whom
* Track how many times the "View Invoice" link was clicked
* View the last time the link was accessed
* Monitor all email activity in the Email History section

### Email History [#email-history]

View the complete email history for each invoice:

<DocImage src="https://storage.pinebill.app/public/docs/image/INV-2025-6V9VLWTD-PineBill-12-09-2025_04_21_PM.webp" alt="Invoice Details Page Overview" maxHeight="350px" className="w-full p-0" />

1. Open your invoice
2. Scroll to the **Email History** section
3. See all sent emails with details including:
   * Recipient email address
   * Email type (Invoice Sent, Reminders)
   * When it was sent
   * Who sent it
   * Click tracking statistics

**Email Types:**

* **Invoice Sent** - Initial invoice email
* **Reminder (Before Due)** - Sent before the due date
* **Reminder (Due Today)** - Sent on the due date
* **Overdue Reminder** - Sent after the due date

## Sharing via Secure Links [#sharing-via-secure-links]

Create shareable links for your invoices with customizable security options.

## How to Share an Invoice [#how-to-share-an-invoice]

1. Open the invoice you want to share
2. Click the **Share PDF** button at the top right
3. Choose your security settings
4. Click **Create Share Link**
5. Copy and share the link

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoices-List-PineBill-12-01-2025_09_02_AM.png" alt="Invoice Details Page Overview" maxHeight="500px" className="w-full p-0" />

## Security Options [#security-options]

### Password Protection [#password-protection]

Add a password to protect your invoice from unauthorized access.

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoices-List-PineBill-12-01-2025_09_07_AM.png" alt="Invoice Details Page Overview" maxHeight="350px" className="w-full p-0" />

**How to use:**

1. Check the **Password Protection** box
2. Enter a password (at least 4 characters)
3. Click the eye icon to show/hide your password
4. Share the password separately from the link (by phone, text, or separate email)

### Expiration Date [#expiration-date]

Make your share link expire automatically after a certain time.

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoices-List-PineBill-12-01-2025_09_09_AM.png" alt="Invoice Details Page Overview" maxHeight="350px" className="w-full p-0" />

**Quick options:**

* **1 hour** - For immediate review
* **1 day** - Short-term access
* **1 week** - Standard invoice delivery

<Callout type="warning">
  If you don't set an expiration, the link will work forever and it will be a public link. You'll
  see a yellow warning when creating a permanent link. Once you created a permanent link, you cannot
  add expiring links to the same invoice later.
</Callout>

### View Limit [#view-limit]

Limit how many times people can view your invoice.

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoices-List-PineBill-12-01-2025_09_08_AM.png" alt="Invoice Details Page Overview" maxHeight="350px" className="w-full p-0" />

**When to use:**

* Controlling who can access the invoice
* Tracking how many times it's been viewed
* Preventing unlimited sharing

**How to use:**

1. Check the **Limit Views** box
2. Enter the maximum number of views (1 to 10,000)
3. The link stops working once it reaches this limit

***

## Managing Your Shares [#managing-your-shares]

View and manage all your share links in one place.

### View All Shares [#view-all-shares]

1. Open your invoice
2. Click the **Manage Shares** button at the top right
3. See all your active and inactive shares

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoices-List-PineBill-12-01-2025_09_15_AM.png" alt="Invoice Details Page Overview" maxHeight="350px" className="w-full p-0" />

### Understanding Share Status [#understanding-share-status]

Each share shows its current status:

* **Active** - Link is working
* **Expired** - Past the expiration date
* **View Limit Reached** - Maximum views used up
* **Revoked** - Manually disabled

You'll also see:

* **Public** badge - No expiration (permanent link)
* **Protected** badge - Password required

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoices-List-PineBill-12-01-2025_09_16_AM.png" alt="Invoice Details Page Overview" maxHeight="350px" className="w-full p-0" />

### What You Can See [#what-you-can-see]

For each share link:

* Who created it and when
* Expiration date (or "Never")
* How many times it's been viewed
* When it was last viewed
* The share URL (for active links)

### Copy a Share Link [#copy-a-share-link]

1. Find the share you want to copy
2. Click the copy icon next to the URL
3. You'll see a confirmation message
4. Paste and share the link

### Delete a Share Link [#delete-a-share-link]

Organization owners can delete any share link:

1. Click the **Manage Shares** button
2. Find the share you want to delete
3. Click the trash icon
4. Confirm deletion

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoices-List-PineBill-12-01-2025_09_17_AM.png" alt="Invoice Details Page Overview" maxHeight="350px" className="w-full p-0" />

<Callout type="warning">
  Once deleted, the link stops working immediately and can't be restored.
</Callout>

## Best Practices for Sharing Invoices [#best-practices-for-sharing-invoices]

### Email Best Practices [#email-best-practices]

1. **Verify email addresses** before sending to avoid delivery issues
2. **Add personal messages** to build customer relationships
3. **Check email history** to confirm delivery and track engagement
4. **Follow up** if the invoice link hasn't been clicked after a few days
5. **Use professional language** in custom messages

### Secure Link Best Practices [#secure-link-best-practices]

1. **Always use passwords** for sensitive invoices
2. **Set expiration dates** to limit exposure
3. **Check view counts** to see who's accessed your invoice
4. **Delete old shares** you're no longer using
5. **Create new links** for different recipients
6. **Send passwords separately** from the share link

### General Tips [#general-tips]

* **Combine both methods** for maximum flexibility
* **Monitor tracking data** to understand customer engagement
* **Keep customer emails updated** in your customer database
* **Use reminders** for overdue invoices to automate follow-ups

## What Recipients See [#what-recipients-see]

When someone clicks your share link:

* They see the full invoice PDF
* They can download it (if enabled)
* They enter the password (if you set one)
* No login required
* Clean, simple view

<DocImage src="https://storage.pinebill.app/public/docs/image/PineBill-Invoice-Software-for-Small-Mid-Sized-Businesses-12-01-2025_09_19_AM.webp" alt="Invoice Details Page Overview" maxHeight="500px" className="w-full p-0" />

## Quick Reference [#quick-reference]

### Email Features [#email-features]

| Feature        | What it does                     | Limit              |
| -------------- | -------------------------------- | ------------------ |
| Custom Message | Personal message in email        | 500 characters     |
| PDF Attachment | Invoice PDF attached to email    | Included           |
| Email Tracking | Track link clicks and engagement | Unlimited tracking |
| Email History  | View all sent emails for invoice | Complete history   |

### Secure Link Features [#secure-link-features]

| Feature            | What it does                  | Maximum              |
| ------------------ | ----------------------------- | -------------------- |
| Password           | Requires password to view     | 4 characters minimum |
| Expiration         | Link stops working after date | 7 days from now      |
| View Limit         | Maximum number of views       | 10,000 views         |
| Shares per Invoice | How many links you can create | Unlimited            |

## Troubleshooting [#troubleshooting]

<Accordions type="single">
  <Accordion title="Email not sending" id="email-not-sending">
    **Common causes:**

    * Missing customer email address - update customer information
    * Invalid email format - check the email address is correct
    * Invoice PDF not generated - regenerate the invoice

    If the problem persists, check your SMTP configuration.
  </Accordion>

  <Accordion title="Customer didn't receive the email" id="email-not-received">
    **Steps to resolve:** 1. Check the Email History to confirm it was sent 2. Ask the customer to
    check their spam/junk folder 3. Verify the email address is correct 4. Resend the email or create
    a secure link as an alternative
  </Accordion>

  <Accordion title="Email link not being clicked" id="email-not-clicked">
    The Email History shows if the "View Invoice" link has been clicked. If not clicked after a few
    days: - Follow up with the customer by phone or text - Resend the email - Create a secure link and
    share it via other channels
  </Accordion>

  <Accordion title="This link has expired" id="link-expired">
    The link passed its expiration date. Create a new share link or resend the invoice via email.
  </Accordion>

  <Accordion title="View limit has reached" id="view-limit-reached">
    Too many people viewed it. Create a new link with a higher limit or no limit.
  </Accordion>

  <Accordion title="Link not found" id="link-not-found">
    The link was deleted or doesn't exist. Ask for a new link or request the invoice be sent via
    email.
  </Accordion>

  <Accordion title="Can't access password-protected link" id="cant-access-password">
    Make sure you have both the link AND the password. Check that you entered the password correctly (it's case-sensitive).
  </Accordion>
</Accordions>

<Callout type="info">
  Only organization owners can delete share links. Emails can be sent by any team member with access
  to the invoice.
</Callout>


# Invoice Statuses (/docs/invoices/invoice-statuses)





## Status Overview [#status-overview]

PineBill uses five distinct status codes to track invoice lifecycle:

<DocImage src="https://storage.pinebill.app/public/docs/image/invoice-statues-thumb.png" alt="First Invoice Screenshot" maxHeight="400px" className="w-full p-0" />

| Status           | Purpose                        | When to Use                                                                        | Automatic Behavior                                                                 |
| ---------------- | ------------------------------ | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| ⚪ **DRAFT**      | Invoice is being prepared      | Creating new invoice<br />Making edits before sending<br />Incomplete invoice data | None                                                                               |
| 🔵 **SENT**      | Invoice sent, awaiting payment | Invoice delivered to customer<br />Payment expected<br />Within due date           | None                                                                               |
| 🟢 **PAID**      | Payment received and confirmed | Customer payment received in full<br />Transaction verified                        | Sets `paidDate` to current timestamp<br />Clears `paidDate` when changed from PAID |
| 🔴 **OVERDUE**   | Payment past due date          | Due date has passed<br />Customer payment is late                                  | Manual update required<br />No automatic SENT → OVERDUE transition                 |
| 🟠 **CANCELLED** | Invoice voided                 | Issued in error<br />Customer order cancelled<br />Superseded by corrected version | None                                                                               |

## Status Transitions [#status-transitions]

Common status workflows:

**Standard flow:**

```
DRAFT → SENT → PAID
```

**Late payment flow:**

```
DRAFT → SENT → OVERDUE → PAID
```

**Cancelled flow:**

```
DRAFT → CANCELLED
SENT → CANCELLED
```

## Manual vs Automatic [#manual-vs-automatic]

**Manual changes required:**

* All status transitions must be manually updated
* No automatic SENT → OVERDUE transition

**Automatic behavior:**

* PAID status sets `paidDate` timestamp
* Changing from PAID clears `paidDate`

## Changing Status [#changing-status]

### Single Invoice [#single-invoice]

You can change the status of a single invoice in two ways:

1. **From the invoice list:** Click on the status badge to open the status selector
2. **From invoice details:** Click the status badge in the invoice details page

### Bulk Status Change [#bulk-status-change]

Update multiple invoices at once:

1. Select invoices using the checkboxes in the invoice list
2. Click **Change Status** in the bulk actions bar
3. Choose the new status
4. Confirm the change

<Callout type="tip">
  Bulk status change is useful for marking multiple invoices as paid after receiving a batch
  payment, or updating sent invoices to overdue status.
</Callout>

## Status in Reports [#status-in-reports]

**Outstanding balance** includes:

* SENT invoices
* OVERDUE invoices

**Dashboard metrics** show:

* Count per status
* Days overdue calculation for OVERDUE invoices
* Overdue identification: `status IN (SENT, OVERDUE) AND dueDate < today`


# Invoice Templates (/docs/invoices/invoice-templates)





## Available Templates [#available-templates]

PineBill offers four professionally designed invoice templates. Select your preferred template when creating an invoice or set a default in [Invoice Settings](/docs/invoices/invoice-settings).

### Standard Template [#standard-template]

Clean, professional design suitable for any business. A balanced default layout that works for all industries.

<DocImage src="https://storage.pinebill.app/public/images/invoice-templates/1.webp" alt="Standard Invoice Template Preview" maxHeight="550px" className="w-full p-0" />

### Bold Professional Template [#bold-professional-template]

Contemporary design with a strong dark header. Creates visual impact and conveys authority.

<DocImage src="https://storage.pinebill.app/public/images/invoice-templates/2.webp" alt="Bold Professional Template Preview" maxHeight="550px" className="w-full p-0" />

### Mono Template [#mono-template]

Clean, minimal design with a monospace aesthetic. Perfect for tech companies and modern businesses.

<DocImage src="https://storage.pinebill.app/public/images/invoice-templates/3.webp" alt="Mono Template Preview" maxHeight="550px" className="w-full p-0" />

### Startup Modern Template [#startup-modern-template]

Modern and sleek style designed for startups and creative agencies.

<DocImage src="https://storage.pinebill.app/public/images/invoice-templates/4.webp" alt="Startup Modern Template Preview" maxHeight="550px" className="w-full p-0" />

## Comparison [#comparison]

| Feature           | Standard    | Bold Professional | Mono       | Startup Modern |
| ----------------- | ----------- | ----------------- | ---------- | -------------- |
| **Style**         | Traditional | Corporate         | Minimalist | Contemporary   |
| **Best for**      | General use | B2B, Enterprise   | Tech, SaaS | Startups       |
| **Visual Impact** | Subtle      | Bold              | Clean      | Modern         |
| **Header**        | Light       | Dark              | Minimal    | Sleek          |

## Choosing a Template [#choosing-a-template]

Consider your business type and client expectations:

* **Standard**: Safe choice for any business, professional without being flashy
* **Bold Professional**: Great for corporate clients who expect a premium look
* **Mono**: Perfect for tech companies, developers, and SaaS businesses
* **Startup Modern**: Ideal for creative agencies, startups, and modern brands

<Callout type="tip">
  Set your preferred template as default in [Invoice Settings](/docs/invoices/invoice-settings) to
  save time when creating invoices.
</Callout>


# Common Invoice Use Cases (/docs/invoices/invoice-use-cases)





## Use Cases Overview [#use-cases-overview]

Discover how different business types can leverage PineBill's invoice management features effectively.

| Business Type             | Scenario                                    | Invoice Mode | Setup & Configuration                                                                                                                          | Key Features                                                                                                                     |
| ------------------------- | ------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Freelance Consultant**  | Hourly billing for consulting services      | Hourly Mode  | Different service types (Consulting, Strategy, Implementation)<br />Different hourly rates per service type<br />Time tracking in descriptions | Multiple hourly rates<br />Time-based billing<br />Example: 8 hrs × $150/hr + 2 hrs × $200/hr = $1,600                           |
| **E-commerce Business**   | Invoicing for product sales                 | Product Mode | Detailed product catalog with SKUs<br />Product photos<br />Shipping costs<br />Tax rates                                                      | SKU tracking<br />Shipping fees<br />Tax calculation<br />Example: 5 items × $25 + 10 items × $15 + tax + shipping = $317.50     |
| **Agency**                | Project-based billing with team assignments | Product Mode | Employee database<br />Invoice assignment to account managers<br />Custom fields for project IDs<br />Detailed scope descriptions              | Team collaboration<br />Project tracking<br />Discount support<br />Example: $5,000 + $1,500 + $800 - 10% discount = $6,570      |
| **Professional Services** | Mixed billing (hourly + fixed-fee)          | Hourly Mode  | Time-based work tracking<br />Temporary items for fixed fees<br />Detailed time entries<br />Professional payment terms (Net 30/60)            | Hybrid billing<br />Professional terms<br />Time precision<br />Example: 4.5 hrs × $300/hr + 2 hrs × $250/hr + $150 fee = $2,000 |
| **Retail/Wholesale**      | Bulk product orders with quantity discounts | Product Mode | Wholesale price catalog<br />Quantity-based discounts<br />Delivery dates                                                                      | Bulk pricing<br />Volume discounts<br />Example: 100 × $12.50 + 50 × $8 - 5% discount + shipping = $1,617.50                     |


# Adding New Products (/docs/products/adding-products)







## Quick Start [#quick-start]

Navigate to the &#x2A;*[Products](/dashboard/products)** page and click the **Create Product** button to add new products to your catalog. Products can be reused across multiple invoices.

<DocImage src="https://storage.pinebill.app/public/docs/image/Products-List-PineBill-04-15-2026_04_02_PM.png" alt="Products page overview" maxHeight="500px" className="w-full p-0" />

***

## Product Types [#product-types]

PineBill supports two types of products:

| Type                   | Description                                                      | Persistence  | Use Case                            |
| ---------------------- | ---------------------------------------------------------------- | ------------ | ----------------------------------- |
| **Regular Products**   | Saved to your catalog and reusable across multiple invoices      | Permanent    | Recurring items, standard offerings |
| **Temporary Products** | Created on-the-fly during invoice creation, not saved to catalog | Invoice-only | One-time items, custom services     |

This guide covers **Regular Products**. For temporary products, see [Creating Invoices - Temporary Products](/docs/invoices/creating-invoices#temporary-products).

***

## Product Fields [#product-fields]

| Field       | Required | Description                                | Max Length | Notes                                          |
| ----------- | -------- | ------------------------------------------ | ---------- | ---------------------------------------------- |
| Name        | Yes      | Product or service name                    | 100 chars  | Displayed on invoices and in product lists     |
| Model       | No       | Model number, SKU, or variant identifier   | 100 chars  | Helps differentiate similar products           |
| Price       | Yes      | Unit price in your default currency        | -          | Must be a positive number                      |
| Description | No       | Detailed product information               | 500 chars  | Shown in product lists and search results      |
| Category    | No       | Product category for organization          | -          | Select from existing or create new category    |
| Photo       | No       | Product image                              | -          | Supports JPG, PNG, WEBP formats. Max 5MB       |
| Active      | Yes      | Whether product is available for selection | -          | Inactive products hidden from invoice creation |

***

## Creating a Product [#creating-a-product]

### Step 1: Open Product Dialog [#step-1-open-product-dialog]

1. Navigate to &#x2A;*[Products](/dashboard/products)**
2. Click **Create Product** button (top-right)
3. The product creation dialog will open

<DocImage src="https://storage.pinebill.app/public/docs/image/Products-List-PineBill-12-01-2025_08_07_PM.webp" alt="Create product button highlighted" maxHeight="400px" className="w-full p-0" />

### Step 2: Fill Product Details [#step-2-fill-product-details]

**Required Fields:**

```
Product Name: Premium Laptop *
Price: 1299.99 *
```

**Optional Fields:**

```
Model: XPS-15-2024
Description: 15.6" display, 16GB RAM, 512GB SSD, Intel i7
Category: Electronics
Photo: [Upload image]
✓ Active Product
```

### Step 3: Upload Photo (Optional) [#step-3-upload-photo-optional]

Products with photos are easier to identify and look more professional:

1. Click the **Upload Photo** button or drag-and-drop area
2. Select an image file (JPG, PNG, or WEBP)
3. Maximum file size: 2MB
4. Image will be automatically uploaded to cloud storage
5. Preview appears in the form

**Photo Tips:**

* Use square images (1:1 ratio) for best display
* Recommended size: 500x500px minimum
* Clear product images work best
* Photos appear in product lists and the inline product search dropdown

### Step 4: Assign Category (Optional) [#step-4-assign-category-optional]

Organize products by assigning a category:

1. Click the **Category** dropdown
2. Select an existing category
3. Or click **Create New Category** to add one
4. Categories help filter and organize your product list

See [Product Categories](/docs/products/product-categories) for more details.

### Step 5: Set Active Status [#step-5-set-active-status]

The **Active Product** checkbox controls visibility:

* **Checked** (default): Product appears in search results and product selector
* **Unchecked**: Product hidden from search and selection but remains in catalog

***

## Temporary Products [#temporary-products]

Temporary products are created during invoice generation and are NOT saved to your catalog.

### When to Use Temporary Products [#when-to-use-temporary-products]

* One-time services or custom work
* Client-specific items that won't be reused
* Quick invoices without adding to catalog

### Creating Temporary Products [#creating-temporary-products]

1. During invoice or estimate creation, go to the **Products** tab
2. In the **inline product row** at the bottom of the table, type a product name that doesn't match any catalog product
3. Fill in the remaining fields in the same row:
   * Model/SKU (optional)
   * Quantity (defaults to 1)
   * Price
4. Press **Enter** or click outside the row to add it
5. The product is added to the invoice but not saved to your catalog

<Callout type="info">
  You can also edit the name, model, quantity, and price of temporary products after adding them by
  clicking directly on the value in the table.
</Callout>

**Temporary vs Regular:**

| Feature             | Regular Product | Temporary Product       |
| ------------------- | --------------- | ----------------------- |
| Saved to catalog    | ✓ Yes           | ✗ No                    |
| Reusable            | ✓ Yes           | ✗ No (one invoice only) |
| Has photo           | ✓ Optional      | ✗ Not supported         |
| Has category        | ✓ Optional      | ✗ Not supported         |
| Can be edited later | ✓ Yes           | ✗ No                    |

***

## Common Errors [#common-errors]

<Accordions type="single">
  <Accordion title="Product with this name already exists" id="duplicate-name">
    **Problem**: You're creating a product with a name that already exists in your catalog.

    **Solution**: Product names don't need to be unique - you can proceed. Consider adding a model number to differentiate similar products.
  </Accordion>

  <Accordion title="Price must be a positive number" id="invalid-price">
    **Problem**: Price cannot be zero or negative.

    **Solution**: Enter a valid number with up to 2 decimal places. All products must have a price greater than 0.
  </Accordion>

  <Accordion title="Photo upload failed" id="photo-upload-error">
    **Problem**: Image upload was unsuccessful.

    **Solution**: Check the following:

    * File size must be under 5MB
    * Only JPG, PNG, or WEBP formats are supported
    * Ensure you have a stable internet connection
    * Try a different image file
  </Accordion>

  <Accordion title="Cannot delete product" id="cannot-delete">
    **Problem**: The product is currently used in existing invoices.

    **Solution**: Products used in invoices cannot be deleted to maintain data integrity. Instead, set the product to inactive to hide it from future invoice creation.
  </Accordion>
</Accordions>

***

## Related Topics [#related-topics]

* [Product Categories](/docs/products/product-categories) - Organize products with categories
* [Product Properties](/docs/products/product-properties) - Add custom attributes to products
* [Creating Invoices](/docs/invoices/creating-invoices) - Add products to invoices


# Bulk Import Products (/docs/products/bulk-import)





## Overview [#overview]

You can import up to **5,000 products** at once by uploading a CSV file. The import wizard walks you through four steps: upload, column mapping, preview, and results.

***

## Starting an Import [#starting-an-import]

Navigate to &#x2A;*[Products](/dashboard/products)** and click the **Import** button next to the Create Product button.

<DocImage src="https://storage.pinebill.app/public/docs/image/Products-List-PineBill-02-09-2026_10_50_AM.webp" alt="Import button on products page" maxHeight="400px" className="w-full p-0" />

***

## Step 1: Upload CSV [#step-1-upload-csv]

Upload your CSV file or download a template to get started.

* Click **Download Template** to get a pre-formatted CSV with the correct headers
* Drag and drop your CSV file or click to browse
* The file must be a valid `.csv` file with headers in the first row
* Maximum **5,000 rows** per import

<DocImage src="https://storage.pinebill.app/public/docs/image/Products-List-PineBill-02-09-2026_10_53_AM.webp" alt="Upload step of the import dialog" maxHeight="500px" className="w-full p-0" />

### CSV Template [#csv-template]

The template includes these columns:

| Column      | Required                              | Example          |
| ----------- | ------------------------------------- | ---------------- |
| Name        | <u className="text-primary">Yes\*</u> | Widget Pro       |
| Model       | No                                    | WP-100           |
| Price       | <u className="text-primary">Yes\*</u> | 29.99            |
| Description | No                                    | A premium widget |
| Active      | No                                    | true             |

**Sample CSV:**

```csv
Name,Model,Price,Description,Active
Widget Pro,WP-100,29.99,A premium widget,true
Basic Widget,BW-200,9.99,Standard widget,true
Custom Service,,150.00,Hourly consulting,false
```

***

## Step 2: Map Columns [#step-2-map-columns]

Map your CSV columns to product fields. The wizard auto-detects common column names (e.g., "product name", "sku", "unit price"), but you can adjust the mapping manually.

* Required fields (**Name**, **Price**) must be mapped before proceeding
* Unmapped optional fields will be skipped
* Click **Reset** to restore auto-detected mappings

<DocImage src="https://storage.pinebill.app/public/docs/image/Products-List-PineBill-02-09-2026_11_01_AM.webp" alt="Column mapping step" maxHeight="500px" className="w-full p-0" />

***

## Step 3: Preview [#step-3-preview]

Review parsed data before importing. The preview shows:

* Total rows parsed
* Valid rows (will be imported)
* Invalid rows with specific error details per field

Only valid rows are imported. Fix any issues in your CSV and re-upload if needed.

<DocImage src="https://storage.pinebill.app/public/docs/image/Products-List-PineBill-02-09-2026_11_03_AM.webp" alt="Preview step showing valid and invalid rows" maxHeight="500px" className="w-full p-0" />

***

## Step 4: Results [#step-4-results]

After clicking **Import**, the wizard processes your data in batches of 100 rows and shows a progress indicator. Once complete, you'll see:

* Number of products created
* Number of rows skipped (duplicates or errors)
* Specific error messages for failed rows

<DocImage src="https://storage.pinebill.app/public/docs/image/Products-List-PineBill-02-09-2026_11_04_AM.webp" alt="Import results summary" maxHeight="500px" className="w-full p-0" />

***

## Field Details [#field-details]

### Active Column [#active-column]

The **Active** column accepts multiple formats:

| Value                               | Interpreted As   |
| ----------------------------------- | ---------------- |
| `true`, `1`, `yes`, `y`, `active`   | Active           |
| `false`, `0`, `no`, `n`, `inactive` | Inactive         |
| Empty or missing                    | Active (default) |

### Price Column [#price-column]

Prices are parsed as numbers. Currency symbols and commas are stripped automatically (e.g., `$1,299.99` becomes `1299.99`). Must be a positive number.

***

## Related Topics [#related-topics]

* [Adding Products](/docs/products/adding-products) - Add products one by one
* [Product Categories](/docs/products/product-categories) - Organize imported products
* [Bulk Import Customers](/docs/customers/bulk-import) - Import customers via CSV


# Product Categories (/docs/products/product-categories)





## Quick Start [#quick-start]

Product categories help you organize your products into logical groups. The main management entry point is &#x2A;*[Settings](/dashboard/setup)** → **Product*&#x2A; → &#x2A;*[Product Categories](/dashboard/categories)**. You can also create categories on-the-fly when adding products.

<DocImage src="https://storage.pinebill.app/public/docs/image/Products-List-PineBill-12-01-2025_07_58_PM.png" alt="Products page showing category filtering" maxHeight="500px" className="w-full p-0" />

***

## Category Fields [#category-fields]

| Field       | Required | Description                                  | Max Length | Notes                                                            |
| ----------- | -------- | -------------------------------------------- | ---------- | ---------------------------------------------------------------- |
| Name        | Yes      | Category name displayed in lists and filters | 50 chars   | Must be unique within your organization                          |
| Description | No       | Additional information about the category    | 200 chars  | For internal reference only                                      |
| Color       | No       | Hex color code for visual identification     | -          | Defaults to `#000000`. Must be valid hex format (e.g. `#FF5733`) |
| Active      | Yes      | Whether category is available for use        | -          | Inactive categories hidden from product selection                |

***

## Creating Categories [#creating-categories]

### Method 1: From Settings [#method-1-from-settings]

1. Open &#x2A;*[Settings](/dashboard/setup)**
2. In **Product*&#x2A;, click &#x2A;*[Product Categories](/dashboard/categories)**
3. Click **Create Category**
4. Fill in category details
5. Click **Create Category** to save

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-04-15-2026_04_41_PM.png" alt="Products page showing category filtering" maxHeight="500px" className="w-full p-0" />

### Method 2: During Product Creation [#method-2-during-product-creation]

1. Open the product creation dialog
2. In the Category field, click "Create New"
3. Fill in the quick category form
4. Category is created and automatically selected for your product

***

## Managing Categories [#managing-categories]

### Viewing Categories [#viewing-categories]

Categories appear in:

* Product list filters (dropdown at top of products page)
* Product creation/edit forms (category selector)
* Product table rows (colored badge next to product name)

### Editing Categories [#editing-categories]

1. Open &#x2A;*[Settings](/dashboard/setup)**
2. Go to &#x2A;*[Product Categories](/dashboard/categories)**
3. Find the category in the list
4. Click the edit icon
5. Update category details
6. Click **Save Changes**

**Editable fields:**

* Name
* Description
* Color
* Active status

### Deactivating Categories [#deactivating-categories]

Deactivating a category:

* Hides it from product selection dropdowns
* Does NOT remove it from existing products
* Products with inactive categories still display the category badge
* Can be reactivated anytime

To deactivate:

1. Edit the category
2. Uncheck "Active Category"
3. Save changes

### Deleting Categories [#deleting-categories]

Categories can only be deleted if:

* No products are currently assigned to the category
* The category is not used in any invoices

To delete:

1. Remove the category from all assigned products first
2. Open &#x2A;*[Product Categories](/dashboard/categories)**
3. Click delete icon
4. Confirm deletion

***

## Related Topics [#related-topics]

* [Adding Products](/docs/products/adding-products) - Create new products with categories
* [Product Properties](/docs/products/product-properties) - Add custom attributes to products
* [Creating Invoices](/docs/invoices/creating-invoices) - Add products to invoices


# Product Properties (/docs/products/product-properties)







## Quick Start [#quick-start]

Product Properties allow you to define custom attributes for your products beyond the standard fields. Open them from &#x2A;*[Settings](/dashboard/setup)** → **Product*&#x2A; → &#x2A;*[Product Properties](/dashboard/properties)** to create definitions that can be assigned to any product in your catalog.

***

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-01-30-2026_09_34_AM.webp" alt="Products Properties Page" maxHeight="500px" className="w-full p-0" />

## What Are Product Properties? [#what-are-product-properties]

Product properties are organization-defined custom fields that extend product information. For example:

* **Weight** (number with unit "kg")
* **Color** (select from predefined options)
* **Material** (text field)
* **Warranty Expiry** (date)
* **In Stock** (boolean yes/no)

Properties help you:

* Track product specifications consistently
* Filter products by custom attributes
* Include detailed product information on invoices
* Standardize product data across your organization

***

## Property Types [#property-types]

PineBill supports five property types to accommodate different data needs:

| Type        | Description                       | Input Control | Example Use Case                  |
| ----------- | --------------------------------- | ------------- | --------------------------------- |
| **String**  | Free-form text input              | Text field    | Material, Brand, SKU              |
| **Number**  | Numeric values with optional unit | Number input  | Weight (kg), Length (cm)          |
| **Boolean** | Yes/No toggle                     | Switch        | In Stock, Fragile, Featured       |
| **Select**  | Choose from predefined options    | Dropdown      | Color, Size, Condition            |
| **Date**    | Date picker for temporal data     | Date picker   | Warranty Expiry, Manufacture Date |

***

## Property Definition Fields [#property-definition-fields]

| Field      | Required    | Description                                  | Notes                                         |
| ---------- | ----------- | -------------------------------------------- | --------------------------------------------- |
| Name       | Yes         | Display name shown in forms and lists        | Max 50 characters                             |
| Key        | Yes         | Unique identifier (auto-generated from name) | Lowercase kebab-case (e.g., `my-property`)    |
| Type       | Yes         | Data type for the property value             | STRING, NUMBER, BOOLEAN, SELECT, or DATE      |
| Unit       | No          | Unit of measurement for NUMBER type          | Max 20 characters (e.g., kg, cm, lbs)         |
| Options    | Conditional | Predefined choices for SELECT type           | Required for SELECT type (at least 1 option)  |
| Required   | No          | Whether products must have this property set | Default: false                                |
| Sort Order | No          | Order in which property appears in forms     | Default: 0 (lower numbers appear first)       |
| Active     | Yes         | Whether property is available for use        | Inactive properties hidden from product forms |

***

## Creating Property Definitions [#creating-property-definitions]

### Step 1: Navigate to Properties Page [#step-1-navigate-to-properties-page]

1. Open &#x2A;*[Settings](/dashboard/setup)**
2. In **Product*&#x2A;, click &#x2A;*[Product Properties](/dashboard/properties)**
3. Click the **New Property** button (top-right)
4. The property creation dialog will open

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-04-15-2026_04_44_PM.png" alt="Products Properties Page" maxHeight="500px" className="w-full p-0" />

### Step 2: Configure the Property [#step-2-configure-the-property]

**Basic Configuration:**

```
Property Name: Weight *
Property Key: weight (auto-generated)
Type: Number *
```

**Type-Specific Configuration:**

For **Number** type:

```
Unit: kg
```

For **Select** type:

```
Options: Red, Blue, Green, Black, White
```

**Additional Options:**

```
☐ Required Property (products must have this value set)
Sort Order: 0
```

### Step 3: Save the Property [#step-3-save-the-property]

Click **Create Property** to save. The property will immediately be available for assignment to products.

***

## Managing Property Definitions [#managing-property-definitions]

### Viewing Properties [#viewing-properties]

The Property Definitions table shows:

* Property name and key
* Data type with icon indicator
* Unit (for NUMBER type)
* Options count (for SELECT type)
* Required status
* Active status
* Number of products using this property

### Editing Properties [#editing-properties]

1. Click the edit icon on any property row
2. Modify the property details
3. Click **Save Changes**

**Important:** Changing the type of a property that is already assigned to products may cause data inconsistencies. It's recommended to create a new property instead.

### Toggling Active Status [#toggling-active-status]

* Click the toggle switch in the Active column
* Inactive properties are hidden from product forms
* Existing property values on products are preserved
* Can be reactivated anytime

### Deleting Properties [#deleting-properties]

Properties can only be deleted if:

* No products currently have values for this property

To delete:

1. Remove the property value from all products first
2. Click the delete icon on the property row
3. Confirm deletion

***

## Assigning Properties to Products [#assigning-properties-to-products]

### From Product Details Page [#from-product-details-page]

<DocImage src="https://storage.pinebill.app/public/docs/image/Products-List-PineBill-01-30-2026_09_43_AM.webp" alt="Products Properties Page" maxHeight="500px" className="w-full p-0" />

1. Navigate to a product's detail page or [Product List](/dashboard/products)
2. Find the **Properties** section
3. Click **Edit Properties**
4. Fill in values for each property definition
5. Click **Save Properties**

<DocImage src="https://storage.pinebill.app/public/docs/image/Products-List-PineBill-01-30-2026_09_45_AM.webp" alt="Products Properties Page" maxHeight="500px" className="w-full p-0" />

### Property Input Types [#property-input-types]

Based on the property definition type, you'll see different input controls:

* **String**: Text input field
* **Number**: Number input with unit suffix displayed
* **Boolean**: Toggle switch (Yes/No)
* **Select**: Dropdown with predefined options
* **Date**: Date picker calendar

### Required Properties [#required-properties]

Properties marked as required will show:

* An asterisk (\*) next to the label
* Validation error if left empty when saving

***

## Filtering Products by Properties [#filtering-products-by-properties]

Product Properties integrate with the product filtering system, allowing you to find products based on their custom attributes.

### Available Filters by Type [#available-filters-by-type]

| Type        | Filter Options                      |
| ----------- | ----------------------------------- |
| **String**  | Contains text search                |
| **Number**  | Min/Max range filter                |
| **Boolean** | Yes, No, or Any                     |
| **Select**  | Multi-select from available options |
| **Date**    | Date range (from/to)                |

### Using Property Filters [#using-property-filters]

<DocImage src="https://storage.pinebill.app/public/docs/image/Products-List-PineBill-01-30-2026_09_47_AM.webp" alt="Products Properties Page" maxHeight="500px" className="w-full p-0" />

1. Go to the &#x2A;*[Products](/dashboard/products)** page
2. Expand the **Property Filters** section in the filter panel
3. Set filters for the properties you want to search by
4. Products matching all criteria will be displayed

Property filters work in combination with other product filters (category, status, search).

***

## Common Errors [#common-errors]

<Accordions type="single">
  <Accordion title="A property with this key already exists" id="duplicate-key">
    **Problem**: You're creating a property with a key that already exists.

    **Solution**: Property keys must be unique within your organization. Either:

    * Use a different name (key is auto-generated)
    * Manually modify the key field to something unique
  </Accordion>

  <Accordion title="Cannot delete property that is used by products" id="property-in-use">
    **Problem**: The property has values assigned to one or more products.

    **Solution**: Remove the property value from all products first, then delete the definition. Alternatively, deactivate the property to hide it from forms while preserving existing data.
  </Accordion>

  <Accordion title="SELECT type requires at least one option" id="select-no-options">
    **Problem**: You're creating a SELECT property without providing options.

    **Solution**: Add at least one option value. Click the "Add Option" button and enter the available choices for this property.
  </Accordion>

  <Accordion title="Key must be lowercase kebab-case" id="invalid-key-format">
    **Problem**: The property key contains invalid characters.

    **Solution**: Keys must use lowercase letters, numbers, and hyphens only (e.g., `my-property`, `weight-kg`). The key is auto-generated from the name, but you can edit it manually.
  </Accordion>
</Accordions>

***

## Related Topics [#related-topics]

* [Adding Products](/docs/products/adding-products) - Create products with custom properties
* [Product Categories](/docs/products/product-categories) - Organize products with categories
* [Creating Invoices](/docs/invoices/creating-invoices) - Add products to invoices


# Creating Projects (/docs/projects/creating-projects)







## Quick Start [#quick-start]

Go to &#x2A;*[Dashboard](/dashboard)*&#x2A; -> &#x2A;*[Projects](/dashboard/projects)** and click **New Project**.

<DocImage src="https://storage.pinebill.app/public/docs/image/Projects-PineBill-05-12-2026_03_43_PM.png" alt="Create project dialog" maxHeight="500px" className="w-full p-2" />

***

## Project Fields [#project-fields]

| Field           | Required | Notes                                                |
| --------------- | -------- | ---------------------------------------------------- |
| **Name**        | Yes      | Project name, up to 160 characters                   |
| **Description** | No       | Brief summary of the project, up to 1,000 characters |
| **Status**      | No       | Active (default), Pending, or Completed              |
| **Customer**    | No       | Link the project to a customer                       |
| **Budget**      | No       | Total project budget, must be zero or greater        |
| **Currency**    | No       | Budget currency, defaults to USD                     |
| **Start Date**  | No       | When the project begins, defaults to today           |
| **End Date**    | No       | Target completion date                               |
| **Assigned To** | No       | Team member responsible for the project              |

***

## Step-by-Step Guide [#step-by-step-guide]

<Steps>
  <Step>
    ### 1. Open the Project Form [#1-open-the-project-form]

    1. Go to &#x2A;*[Projects](/dashboard/projects)**
    2. Click **New Project**
    3. Enter a project name
  </Step>

  <Step>
    ### 2. Add Optional Details [#2-add-optional-details]

    Open **More Details** to add:

    * Description
    * Status
    * Customer
    * Budget and currency
    * Start and end dates
    * Assigned team member

    <DocImage src="https://storage.pinebill.app/public/docs/image/Projects-PineBill-05-12-2026_03_44_PM.png" alt="Project form with more details expanded" maxHeight="500px" className="w-full p-2" />
  </Step>

  <Step>
    ### 3. Save [#3-save]

    Click **Create Project**. The project appears in your project list and is ready for tasks, invoices, and other documents.
  </Step>
</Steps>

***

## Editing a Project [#editing-a-project]

Open a project and click the **Edit** button, or use the actions menu on the project list. All fields can be updated after creation.

***

## After Creating [#after-creating]

Once a project is saved, you can:

* Add tasks and track time from the Tasks tab
* Link invoices, estimates, and expenses
* Generate a share link for client visibility
* Update the status as work progresses

***

## Related Topics [#related-topics]

* [Project Management](/docs/projects) - Overview of project features
* [Project Sharing](/docs/projects/project-sharing) - Share project progress with clients
* [Task Management](/docs/tasks) - Create tasks inside projects
* [Customers](/docs/customers/adding-customers) - Add customers before linking to projects


# Project Management (/docs/projects)







## Quick Start [#quick-start]

Use Projects to group tasks, invoices, estimates, and expenses under one workspace. Each project tracks budget, timeline, and assigned team members.

Go to &#x2A;*[Dashboard](/dashboard)*&#x2A; -> &#x2A;*[Projects](/dashboard/projects)**.

<DocImage src="https://storage.pinebill.app/public/docs/image/Projects-PineBill-05-12-2026_03_33_PM.png" alt="Projects list page" maxHeight="500px" className="w-full p-2" />

***

## Key Features [#key-features]

<Cards>
  <Card title="Creating Projects" description="Set up a project with budget, timeline, customer, and team assignment" href="/docs/projects/creating-projects" />

  <Card title="Project Sharing" description="Generate password-protected share links for client visibility" href="/docs/projects/project-sharing" />

  <Card title="Task Management" description="Create tasks, track time, and manage work inside projects" href="/docs/tasks" />

  <Card title="Convert Tasks to Invoices" description="Turn completed task hours into invoice line items" href="/docs/tasks/task-to-invoice" />
</Cards>

***

## Project List [#project-list]

The Projects page shows all projects in your organization.

Each project row displays:

* Project name and description
* Status badge (Active, Pending, or Completed)
* Assigned customer
* Assigned team member
* Budget and currency
* Start and end dates
* Created date

<DocImage src="https://storage.pinebill.app/public/docs/image/Projects-PineBill-05-12-2026_03_33_PM.png" alt="Projects list with columns" maxHeight="400px" className="w-full p-2" />

***

## Project Statuses [#project-statuses]

| Status        | Meaning                                |
| ------------- | -------------------------------------- |
| **Active**    | Work is currently in progress          |
| **Pending**   | Project is planned but not yet started |
| **Completed** | All work is finished                   |

***

## Searching, Filtering, and Sorting [#searching-filtering-and-sorting]

Use the controls above the project list to narrow results.

| Control        | What it does                                                        |
| -------------- | ------------------------------------------------------------------- |
| **Search**     | Searches project name and description                               |
| **Status**     | Filters by Active, Pending, or Completed                            |
| **Sort by**    | Sort by created date, name, status, start date, end date, or budget |
| **Sort order** | Ascending or descending                                             |

Active filters appear as badges. Click **Clear filters** to reset.

<DocImage src="https://storage.pinebill.app/public/docs/image/Projects-PineBill-05-12-2026_03_36_PM.png" alt="Project filter bar" maxHeight="150px" className="w-full p-2" />

***

## Project Detail Page [#project-detail-page]

Click any project to open the detail page. The project header shows the name, status, customer, budget, dates, and assigned team member.

Below the header are five tabs:

### Tasks Tab [#tasks-tab]

Displays all tasks belonging to the project. You can switch between a **Kanban board** (drag-and-drop columns) and a **table list** view. Create new tasks directly from this tab.

<DocImage src="https://storage.pinebill.app/public/docs/image/Projects-PineBill-05-12-2026_03_41_PM.png" alt="Project detail page with tasks tab" maxHeight="500px" className="w-full p-2" />

### Invoices Tab [#invoices-tab]

Lists invoices linked to the project. You can link existing invoices or navigate to linked invoice details.

### Estimates Tab [#estimates-tab]

Lists estimates linked to the project. You can link existing estimates or view linked estimate details.

### Expenses Tab [#expenses-tab]

Lists expenses linked to the project. You can add new expenses directly from this tab or link existing ones.

### Shares Tab [#shares-tab]

Manage share links for the project. Create new share links with optional expiration, view limits, and password protection. See [Project Sharing](/docs/projects/project-sharing) for details.

***

## Linking Documents to a Project [#linking-documents-to-a-project]

From the project detail page, you can link invoices, estimates, and expenses to keep all project-related documents in one place.

* **Link**: Use the link button on the Invoices, Estimates, or Expenses tab to associate an existing document
* **Unlink**: Use the actions menu on any linked document to remove the association

Linking does not move or copy the document. It creates a reference so you can see all related documents from the project.

***

## Deleting Projects [#deleting-projects]

You can delete a project from the actions menu on the project list or from the project detail page.

To delete multiple projects at once, select them using the checkboxes and click **Delete Selected**. You can bulk delete up to 100 projects at a time.

Deleting a project also removes all tasks within it. Linked invoices, estimates, and expenses are unlinked but not deleted.

***

## Permissions [#permissions]

| Role            | Can view | Can create | Can edit     | Can delete |
| --------------- | -------- | ---------- | ------------ | ---------- |
| **Owner/Admin** | Yes      | Yes        | Any project  | Yes        |
| **Member**      | Yes      | Yes        | Own projects | No         |

***

## Common Questions [#common-questions]

<Accordions type="single">
  <Accordion title="What happens to tasks when I delete a project?" id="delete-project-tasks">
    All tasks inside the project are permanently deleted along with their timer history and file attachments. This cannot be undone.
  </Accordion>

  <Accordion title="Can I move a task between projects?" id="move-task">
    Yes. Edit the task and change the project field to move it to a different project, or clear the
    field to make it a standalone task.
  </Accordion>

  <Accordion title="What happens to linked invoices when I delete a project?" id="linked-invoices-delete">
    Linked invoices, estimates, and expenses are unlinked from the project but not deleted. They
    remain accessible from their own pages.
  </Accordion>

  <Accordion title="Is there a limit on how many projects I can create?" id="project-limit">
    Project limits depend on your subscription plan. You will see a message if you reach your plan's project limit.
  </Accordion>
</Accordions>

***

## Related Topics [#related-topics]

* [Creating Projects](/docs/projects/creating-projects) - Set up a new project
* [Project Sharing](/docs/projects/project-sharing) - Share project progress with clients
* [Task Management](/docs/tasks) - Create and manage tasks
* [Time Tracking](/docs/tasks/time-tracking) - Track time spent on tasks
* [Converting Tasks to Invoices](/docs/tasks/task-to-invoice) - Bill clients for task hours


# Project Sharing (/docs/projects/project-sharing)







## Quick Start [#quick-start]

Open a project and go to the **Shares** tab to create a share link.

<DocImage src="https://storage.pinebill.app/public/docs/image/Projects-PineBill-05-12-2026_03_52_PM.png" alt="Project shares tab" maxHeight="400px" className="w-full p-2" />

***

## Creating a Share Link [#creating-a-share-link]

1. Open the project detail page
2. Go to the **Shares** tab
3. Optionally set a password for extra security
4. Click **Create Share Link**
5. Copy the generated URL and send it to your client

<DocImage src="https://storage.pinebill.app/public/docs/image/Projects-PineBill-05-12-2026_03_53_PM.png" alt="Create project share dialog" maxHeight="400px" className="w-full p-2" />

***

## Share Options [#share-options]

| Option         | Description                                                  |
| -------------- | ------------------------------------------------------------ |
| **Password**   | Require a password before the recipient can view the project |
| **Expiration** | Set a date after which the link stops working                |
| **Max Views**  | Limit how many times the link can be opened                  |

All options are optional. Without any restrictions, the link stays active until you revoke it.

***

## What Shared Viewers See [#what-shared-viewers-see]

Recipients who open the share link can view:

* Project name, description, and status
* Budget and currency
* Start and end dates
* Customer name
* Tasks with their status and time spent

Viewers cannot edit the project, start timers, or access any other part of your account.

<DocImage src="https://storage.pinebill.app/public/docs/image/PineBill-Invoice-Software-for-Small-Mid-Sized-Businesses-05-12-2026_03_53_PM.png" alt="Public project share page" maxHeight="500px" className="w-full p-2" />

***

## Revoking a Share Link [#revoking-a-share-link]

To disable an active share link:

1. Open the project detail page
2. Go to the **Shares** tab
3. Click **Revoke** on the active share link

Once revoked, anyone with the link will see an error page. You can create a new share link at any time.

***

## Security [#security]

* **Password protection**: If a password is set, the viewer must enter it before seeing the project. After **10 failed password attempts**, the share is locked for 1 hour.
* **View tracking**: PineBill records when the link was last viewed and how many times it has been opened.
* **Expiration**: Links with an expiration date automatically stop working after that date.

***

## Common Questions [#common-questions]

<Accordions type="single">
  <Accordion title="Can I update a share link after creating it?" id="update-share">
    No. To change share settings, revoke the current link and create a new one with the desired options.
  </Accordion>

  <Accordion title="Can I have multiple active share links for one project?" id="multiple-shares">
    Only one share link can be active per project at a time. Revoke the existing link before creating a new one.
  </Accordion>
</Accordions>

***

## Related Topics [#related-topics]

* [Project Management](/docs/projects) - Overview of project features
* [Invoice Sharing](/docs/invoices/invoice-sharing) - Share invoices with clients


# Creating Recurring Invoices (/docs/recurring-invoices/creating-recurring-invoices)





## Quick Start [#quick-start]

Navigate to **Recurring Invoices → Create** from the sidebar, or click "New Recurring Invoice" from the recurring invoices list page.

<DocImage src="https://storage.pinebill.app/public/docs/image/Recurring-Invoices-PineBill-04-15-2026_03_52_PM.png" alt="Recurring Invoice Generator" maxHeight="500px" className="w-full p-0" />

The generator has a tabbed form on the left and a live summary sidebar on the right. Fill out the five tabs to configure your recurring invoice.

***

## Tab 1: Schedule [#tab-1-schedule]

The Schedule tab defines when and how often invoices are generated.

<DocImage src="https://storage.pinebill.app/public/docs/image/New-Recurring-Invoice-PineBill-03-10-2026_03_10_PM.png" alt="Schedule Tab" maxHeight="450px" className="w-full p-0" />

### Name [#name]

Give your recurring invoice a descriptive name (e.g., "Monthly hosting for Acme Corp"). This label appears in the list view and notifications.

### Frequency [#frequency]

Select how often invoices should be generated:

| Frequency     | Description        | Anchor Type                      |
| ------------- | ------------------ | -------------------------------- |
| **Weekly**    | Every week         | Day of week (Sun–Sat)            |
| **Biweekly**  | Every two weeks    | Day of week (Sun–Sat)            |
| **Monthly**   | Every month        | Day of month (1–31, or last day) |
| **Quarterly** | Every three months | Day of month (1–31, or last day) |
| **Yearly**    | Once a year        | Day of month (1–31, or last day) |

### Anchor Days [#anchor-days]

After selecting a frequency, choose which days invoices should be generated:

* **Weekly / Biweekly**: Select one or more days of the week (Sunday through Saturday). An invoice is generated for each selected day per cycle.
* **Monthly / Quarterly / Yearly**: Select one or more days of the month (1–31). Use the **L** button to select the last day of the month. An invoice is generated for each selected day per cycle.

<Callout type="info">
  You can select multiple anchor days. For example, selecting the 1st and 15th for a monthly
  schedule generates two invoices per month.
</Callout>

### Time [#time]

Set the hour (00–23) and minute (00, 15, 30, or 45) when invoices should be generated.

**Default**: 09:00

### Timezone [#timezone]

Select the timezone for the schedule. When a customer is selected on the Customer tab, the timezone auto-populates from the customer's timezone setting.

**Default**: Your organization's timezone (falls back to UTC).

<Callout type="info">
  Make sure the timezone is set correctly — it determines the exact time invoices are generated. An
  incorrect timezone can cause invoices to be created hours earlier or later than expected.
</Callout>

### Schedule Preview [#schedule-preview]

As you configure the schedule, the summary sidebar shows a human-readable preview (e.g., "1st and 15th of Every Month at 09:00") along with the next 6 scheduled run dates. This helps you verify that the schedule matches your intentions before creating the recurring invoice.

<DocImage src="https://storage.pinebill.app/public/docs/image/New-Recurring-Invoice-PineBill-03-10-2026_03_15_PM.png" alt="Schedule Preview in Summary Sidebar" maxHeight="400px" className="w-full p-2" />

### Duration [#duration]

Control how long the recurring invoice runs:

| End Type     | Description                                             |
| ------------ | ------------------------------------------------------- |
| **Never**    | Runs indefinitely until manually paused or cancelled    |
| **End Date** | Stops after a specific date                             |
| **Count**    | Stops after generating a set number of invoices (1–999) |

* **Start Date**: When the schedule begins (defaults to today).
* **Due Date Days**: Number of days after the issue date for the payment due date (e.g., 30 for Net 30).

### Email Notifications [#email-notifications]

* **Auto-send**: Toggle whether generated invoices are automatically emailed to recipients. Enabled by default.
* **Recipient Emails**: Add one or more email addresses. When a customer is selected, their email is pre-populated.

***

## Tab 2: Products [#tab-2-products]

Add the line items that will appear on each generated invoice.

<DocImage src="https://storage.pinebill.app/public/docs/image/New-Recurring-Invoice-PineBill-03-10-2026_03_16_PM.png" alt="Products Tab" maxHeight="450px" className="w-full p-2" />

* **Type to Search**: Start typing a product name in the inline row at the bottom of the table. An autocomplete dropdown appears with matching products from your catalog. Recent products appear automatically when you click the field.
* **Select from Catalog**: Click a product in the dropdown to instantly add it with its saved details.
* **Create Inline Temporary Item**: Type a new product name, fill in model, quantity, and price in the same row, then press **Enter** or click outside to add it. Temporary items are not saved to your catalog.
* **Browse All Products**: Click "Browse All Products" at the bottom of the autocomplete dropdown to open the full product selector with filters and multi-select.
* **Drag to Reorder**: Rearrange items by dragging.
* **Inline Editing**: Click to edit quantity and price directly. For temporary items, name and model are also editable.

### Tax & Discount [#tax--discount]

Configure these in the Products tab:

| Setting           | Description                                    |
| ----------------- | ---------------------------------------------- |
| **Shipping Cost** | Fixed shipping amount added to each invoice    |
| **Discount**      | Fixed discount amount subtracted from subtotal |
| **Tax Rate**      | Tax percentage or fixed amount                 |
| **Tax Type**      | Percentage (%) or Fixed amount                 |
| **Tax Included**  | Toggle whether item prices already include tax |

***

## Tab 3: Customer [#tab-3-customer]

Select the customer who will receive the recurring invoices.

<DocImage src="https://storage.pinebill.app/public/docs/image/New-Recurring-Invoice-PineBill-03-10-2026_03_17_PM.png" alt="Customer Tab" maxHeight="400px" className="w-full p-2" />

Click "Select Customer" to browse or search your customer list. Selecting a customer automatically:

* Sets the schedule timezone to the customer's timezone
* Pre-populates the recipient email list with the customer's email

***

## Tab 4: Payment [#tab-4-payment]

Select one or more payment methods to include on each generated invoice.

<DocImage src="https://storage.pinebill.app/public/docs/image/New-Recurring-Invoice-PineBill-03-10-2026_03_19_PM.png" alt="Payment Tab" maxHeight="400px" className="w-full p-2" />

Click "Select Payment Methods" to choose from your saved payment methods (bank transfer, PayPal, cryptocurrency, or custom).

***

## Tab 5: Settings [#tab-5-settings]

Configure invoice appearance and content defaults.

<DocImage src="https://storage.pinebill.app/public/docs/image/New-Recurring-Invoice-PineBill-03-10-2026_03_20_PM.png" alt="Settings Tab" maxHeight="450px" className="w-full p-2" />

### Invoice Settings [#invoice-settings]

| Setting             | Description                       | Default              |
| ------------------- | --------------------------------- | -------------------- |
| **Currency**        | Currency for all invoice amounts  | Organization default |
| **Currency Format** | How currency values are displayed | Invoice settings     |
| **Template**        | PDF template style                | Organization default |
| **Language**        | Invoice label language            | English              |
| **Date Format**     | How dates appear on the invoice   | Month DD, YYYY       |

### Invoice Content [#invoice-content]

* **Terms of Payment**: Payment conditions text (e.g., "Net 30", "Due on receipt").
* **End Message**: A note or thank-you message at the bottom of each invoice.
* **Custom Fields**: Add label/value pairs for additional information (e.g., PO Number, Project ID).

### Assigned Employee [#assigned-employee]

Optionally assign the recurring invoice to an employee. This links all generated invoices to that employee for performance tracking and reporting.

***

## Summary Sidebar [#summary-sidebar]

As you fill out the form, the summary sidebar shows a live preview of your configuration:

* Customer and product count
* Calculated totals (subtotal, discount, tax, shipping, total)
* **Schedule Preview**: A human-readable summary of the frequency (e.g., "1st of Every Month at 09:00") with the next 6 scheduled dates

<DocImage src="https://storage.pinebill.app/public/docs/image/New-Recurring-Invoice-PineBill-03-10-2026_03_15_PM.png" alt="Summary Sidebar with Schedule Preview" maxHeight="500px" className="w-full p-0" />

***

## Creating the Invoice [#creating-the-invoice]

Once all required fields are filled (name, frequency, at least one anchor day, customer, and at least one product), click **Create Recurring Invoice**.

The recurring invoice is created with **Active** status and will generate its first invoice at the next scheduled time.

***

## Related Topics [#related-topics]

* [Managing Recurring Invoices](/docs/recurring-invoices/managing-recurring-invoices) — View, filter, pause, and monitor
* [Invoice Templates](/docs/invoices/invoice-templates) — Template styles for generated invoices
* [Invoice Settings](/docs/invoices/invoice-settings) — Configure default invoice settings


# Introduction (/docs/recurring-invoices)





## Overview [#overview]

Recurring invoices let you automate repetitive billing. Define a schedule, assign a customer and products, and PineBill generates and optionally emails invoices on your behalf — weekly, monthly, quarterly, or at any frequency you choose.

<DocImage src="https://storage.pinebill.app/public/docs/image/Recurring-Invoices-PineBill-03-10-2026_02_52_PM.png" alt="Recurring Invoices List" maxHeight="500px" className="w-full p-4" />

## Key Features [#key-features]

| Feature                 | Description                                                              |
| ----------------------- | ------------------------------------------------------------------------ |
| **Flexible Scheduling** | Weekly, biweekly, monthly, quarterly, or yearly with multi-day anchors   |
| **Auto-Send Email**     | Automatically email generated invoices to one or more recipients         |
| **Run History**         | Full audit trail of every generated invoice with status and timing       |
| **Pause & Resume**      | Temporarily halt a schedule without losing configuration                 |
| **Duration Controls**   | Run indefinitely, until a specific date, or for a set number of invoices |
| **Employee Assignment** | Link recurring invoices to employees for performance tracking            |

## Lifecycle [#lifecycle]

Recurring invoices follow a simple status lifecycle:

```
ACTIVE → PAUSED → ACTIVE (resume)
ACTIVE → COMPLETED (max runs or end date reached)
ACTIVE → CANCELLED
PAUSED → CANCELLED
```

| Status        | Description                                                                |
| ------------- | -------------------------------------------------------------------------- |
| **Active**    | Running on schedule. Invoices are generated at each scheduled time.        |
| **Paused**    | Temporarily stopped. No invoices are generated until resumed.              |
| **Completed** | Finished — reached the end date or maximum number of runs. Terminal state. |
| **Cancelled** | Manually cancelled. Terminal state.                                        |

<Callout type="info">
  Completed and Cancelled are terminal states. Once a recurring invoice reaches either status, it
  cannot be reactivated.
</Callout>

## Run Statuses [#run-statuses]

Each time a recurring invoice executes, a run record is created:

| Run Status  | Meaning                                                           |
| ----------- | ----------------------------------------------------------------- |
| **Success** | Invoice was generated (and emailed if auto-send is on)            |
| **Failed**  | Something went wrong — check the error message in run history     |
| **Skipped** | The run was skipped (e.g., schedule conflict or validation issue) |

## Getting Started [#getting-started]

<Cards>
  <Card title="Creating Recurring Invoices" description="Step-by-step guide to setting up automated billing schedules" href="/docs/recurring-invoices/creating-recurring-invoices" />

  <Card title="Managing Recurring Invoices" description="View, filter, pause, resume, and monitor your recurring invoices" href="/docs/recurring-invoices/managing-recurring-invoices" />
</Cards>


# Managing Recurring Invoices (/docs/recurring-invoices/managing-recurring-invoices)





## List View [#list-view]

Access your recurring invoices from **Recurring Invoices → List** in the sidebar.

<DocImage src="https://storage.pinebill.app/public/docs/image/Recurring-Invoices-PineBill-03-10-2026_02_52_PM.png" alt="Recurring Invoices List View" maxHeight="500px" className="w-full p-2" />

The list displays all recurring invoices with the following columns:

| Column         | Description                                                     |
| -------------- | --------------------------------------------------------------- |
| **Name**       | The recurring invoice name                                      |
| **Customer**   | Assigned customer name                                          |
| **Frequency**  | How often invoices are generated                                |
| **Next Run**   | When the next invoice will be generated (shown for Active only) |
| **Total Runs** | Number of invoices generated so far                             |
| **Status**     | Current lifecycle status                                        |
| **Actions**    | Context menu with available operations                          |

Click any row to open the detail page.

### Search [#search]

Use the search bar to find recurring invoices by name or customer name. Search is case-insensitive with a 300ms debounce.

### Filters [#filters]

Filter the list using the dropdowns:

* **Status**: All Statuses, Active, Paused, Completed, Cancelled
* **Frequency**: All Frequencies, Weekly, Biweekly, Monthly, Quarterly, Semi-annually, Annually

Active filters appear as chips below the filter bar with individual clear buttons and a "Clear all" option.

### Sort & Display [#sort--display]

Open the Sort & Display popover to configure:

| Option               | Choices                                          |
| -------------------- | ------------------------------------------------ |
| **Sort By**          | Name, Next Run, Total Runs, Status, Created Date |
| **Sort Order**       | Ascending, Descending                            |
| **Results Per Page** | 5, 10, 25, 50                                    |

<Callout type="info">
  On mobile, all filters collapse into a bottom sheet triggered by the "Filters & Sort" button.
</Callout>

***

## Detail Page [#detail-page]

Click a recurring invoice to view its full details.

<DocImage src="https://storage.pinebill.app/public/docs/image/Recurring-Invoice-Details-PineBill-03-10-2026_02_56_PM.webp" alt="Recurring Invoice Detail Page" maxHeight="500px" className="w-full p-2" />

The detail page has two columns:

### Main Content (Left) [#main-content-left]

1. **Schedule Card**: Next run date (highlighted), frequency, start/end dates, time, timezone, repeat pattern badges, run stats, and auto-send toggle.
2. **Run History**: Paginated table of all runs with columns for scheduled time, status, generated invoice link, email sent, and error details.
3. **Invoice Items**: Product table with subtotal, shipping, discount, tax, and total.

### Sidebar (Right) [#sidebar-right]

* **Customer**: Name and email
* **Assigned Employee**: Name and employee ID (if assigned)
* **Invoice Settings**: Currency, currency format, template, language, tax, discount, shipping
* **Terms & Messages**: Payment terms and end message (if set)
* **Details**: Created date and last run timestamp

***

## Pausing and Resuming [#pausing-and-resuming]

### Pause [#pause]

To temporarily stop a recurring invoice from generating invoices:

1. From the **list view**: Click the three-dot menu on an Active recurring invoice → **Pause**
2. From the **detail page**: Click the **Pause** button in the header

The status changes to **Paused** and no further invoices are generated until resumed.

### Resume [#resume]

To reactivate a paused recurring invoice:

1. From the **list view**: Click the three-dot menu on a Paused recurring invoice → **Resume**
2. From the **detail page**: Click the **Resume** button in the header

The status changes back to **Active**. If the next scheduled run was in the past, it is automatically advanced to the next valid future time.

<Callout type="info">
  Only Active invoices can be paused, and only Paused invoices can be resumed. Completed and
  Cancelled invoices cannot be reactivated.
</Callout>

***

## Editing Recurring Invoices [#editing-recurring-invoices]

You can update any field on a recurring invoice that is in **Active** or **Paused** status. Changes to schedule parameters (frequency, anchor days, time, timezone) automatically recalculate the next run date.

<Callout type="warn">
  Recurring invoices in Completed or Cancelled status cannot be edited.
</Callout>

***

## Deleting Recurring Invoices [#deleting-recurring-invoices]

To delete a recurring invoice:

1. From the **list view**: Click the three-dot menu → **Delete**
2. From the **detail page**: Click the **Delete** button

A confirmation dialog appears before deletion. Deleting a recurring invoice permanently removes it along with all run history. Previously generated invoices are not affected.

***

## Run History [#run-history]

Each time a recurring invoice executes, a run record is created with one of three statuses:

| Status      | Badge Color | Description                                                         |
| ----------- | ----------- | ------------------------------------------------------------------- |
| **Success** | Green       | Invoice was generated successfully. Links to the generated invoice. |
| **Failed**  | Red         | An error occurred. Check the error message for details.             |
| **Skipped** | Amber       | The run was skipped due to a schedule conflict or validation issue. |

Run history is available on the detail page and shows:

* **Scheduled For**: When the run was supposed to execute
* **Status**: Success, Failed, or Skipped
* **Invoice**: Link to the generated invoice (Success runs only)
* **Email Sent**: Whether the invoice was emailed
* **Error**: Error message (Failed runs only)

***

## Statistics [#statistics]

The recurring invoices list page shows summary statistics at the top:

| Stat                | Description                                   |
| ------------------- | --------------------------------------------- |
| **Active**          | Number of currently active recurring invoices |
| **Paused**          | Number of paused recurring invoices           |
| **Completed**       | Number of completed recurring invoices        |
| **Runs This Month** | Total runs executed in the current month      |

***

## Related Topics [#related-topics]

* [Creating Recurring Invoices](/docs/recurring-invoices/creating-recurring-invoices) — Set up new automated billing
* [Recurring Invoices Overview](/docs/recurring-invoices) — Feature overview and lifecycle
* [Invoice List](/docs/invoices/invoice-list) — Managing one-time invoices


# Subscription (/docs/subscription)







## Quick Start [#quick-start]

Every PineBill account starts with a **7-day free trial*&#x2A; of Pro features. View and manage your subscription from &#x2A;*[Settings](/dashboard/setup)** → **Organization Management*&#x2A; → &#x2A;*[Subscription](/dashboard/subscription)**.

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-04-15-2026_04_34_PM.png" alt="Products page overview" maxHeight="500px" className="mb-4 w-full p-0" />

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-04-15-2026_04_35_PM.png" alt="Products page overview" maxHeight="500px" className="w-full p-0" />

***

## Available Plans [#available-plans]

PineBill offers four subscription tiers to match your business needs, check more details on the [Pricing Page](/pricing):

| Plan           | Price         | Best For            | Key Limits                                     |
| -------------- | ------------- | ------------------- | ---------------------------------------------- |
| **Trial**      | Free (7 days) | Testing PineBill    | 50 invoices/month, 2 members                   |
| **Solo**       | $10/month     | Freelancers         | 100 invoices/month, 1 member                   |
| **Pro**        | $19.9/month   | Growing businesses  | 1,000 invoices/month, 5 members, 10K API calls |
| **Enterprise** | $90/month     | Large organizations | Unlimited invoices, members, API calls         |

<Callout type="info">
  **Save with Annual Billing**: Get 2-3 months free by switching to annual billing. Solo saves
  $30/year, Pro saves $60/year, Enterprise saves $180/year.
</Callout>

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-12-02-2025_08_35_PM.webp" alt="Products page overview" maxHeight="500px" className="w-full p-0" />

***

## Usage Limits & Monitoring [#usage-limits--monitoring]

Each plan includes specific usage limits tracked in your dashboard:

### Monthly Limits (Reset Every Billing Period) [#monthly-limits-reset-every-billing-period]

* **Invoices Generated**: Number of invoices created per month
* **API Calls**: Monthly API requests (Pro and Enterprise only)

### Account Limits (Ongoing State) [#account-limits-ongoing-state]

* **Team Members**: Active organization members
* **Storage**: Total file storage used
* **Max File Size**: Maximum size per file upload
* **Products**: Items in product catalog
* **Categories**: Product category count
* **Customers**: Customer records

<Callout type="warn">
  When you reach a limit, PineBill will prompt you to upgrade or reduce usage before continuing.
</Callout>

***

## Changing Your Plan [#changing-your-plan]

<Steps>
  <Step>
    ### 1. Access Plan Management [#1-access-plan-management]

    1. Open &#x2A;*[Settings](/dashboard/setup)**
    2. Click &#x2A;*[Subscription](/dashboard/subscription)**
    3. Click **Upgrade Now** or **Change Plan** button
    4. Plan comparison dialog opens
  </Step>

  <Step>
    ### 2. Choose Your Plan [#2-choose-your-plan]

    * **Upgrading**: Takes effect immediately with prorated billing
    * **Downgrading**: Takes effect at the end of your current billing period
    * **Billing Cycle**: Choose monthly or annual (annual saves money)

    <Callout type="info">
      You cannot downgrade if your current usage exceeds the target plan's limits. Reduce usage first
      (e.g., remove team members, delete files).
    </Callout>
  </Step>

  <Step>
    ### 3. Complete Checkout [#3-complete-checkout]

    * First-time subscribers: Redirected to Polar checkout
    * Existing subscribers upgrading: Instant upgrade with automatic proration
    * Downgrading: Scheduled for next billing period
  </Step>
</Steps>

***

## Billing Management [#billing-management]

### Billing Portal [#billing-portal]

Access your billing portal to manage:

* View invoices and payment history
* Update payment methods
* Change billing email
* Download receipts

**To access*&#x2A;: Open &#x2A;*[Settings](/dashboard/setup)*&#x2A; → &#x2A;*[Subscription](/dashboard/subscription)**, then click **Billing Portal** (opens in a new tab).

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-12-02-2025_08_38_PM.webp" alt="Products page overview" maxHeight="500px" className="w-full p-4" />

<Callout type="info">
  **Note**: Only organization owners can access billing management features.
</Callout>

### Billing Cycles [#billing-cycles]

* **Monthly**: Billed every month on your subscription start date
* **Annual**: Billed once per year (save 17-25%)
* **Trial**: Free for 7 days, no payment required

***

## Trial Period [#trial-period]

Every new organization gets a **7-day free trial** with Pro plan features:

**Trial Includes:**

* 50 invoices/month
* 50 API calls/month
* 2 team members
* 100MB storage
* All Pro features enabled

**What Happens After Trial:**

* **If you upgrade**: Seamless transition to your chosen paid plan
* **If trial expires**: Account switches to restricted mode until you subscribe

<Callout type="tip">
  You can upgrade to a paid plan anytime during your trial. You'll only be charged after your trial
  period ends.
</Callout>

***

## Canceling Your Subscription [#canceling-your-subscription]

<Steps>
  <Step>
    ### 1. Initiate Cancellation [#1-initiate-cancellation]

    1. Open &#x2A;*[Settings](/dashboard/setup)**
    2. Go to &#x2A;*[Subscription Dashboard](/dashboard/subscription)**
    3. Click **Cancel Subscription** in the Management section
    4. Cancellation dialog opens
  </Step>

  <Step>
    ### 2. Confirm Cancellation [#2-confirm-cancellation]

    1. Optionally provide a cancellation reason (helps us improve)
    2. Review what happens after cancellation
    3. Click **Confirm Cancellation**
  </Step>

  <Step>
    ### 3. End of Billing Period [#3-end-of-billing-period]

    * Your subscription remains **active until your current period ends**
    * You keep full access to paid features until then
    * No refunds for partial months
    * After period ends, account reverts to Trial limits with view-only access
  </Step>
</Steps>

### Reactivating a Canceled Subscription [#reactivating-a-canceled-subscription]

Changed your mind? You can reactivate anytime before your period ends:

1. Open &#x2A;*[Settings](/dashboard/setup)**
2. Go to &#x2A;*[Subscription Dashboard](/dashboard/subscription)**
3. Click **Reactivate** button
4. Subscription continues without interruption

***

## Subscription Statuses [#subscription-statuses]

Your subscription can have different statuses:

| Status         | Meaning                          | What to Do                               |
| -------------- | -------------------------------- | ---------------------------------------- |
| **Trialing**   | In 7-day trial period            | Upgrade anytime or wait for trial to end |
| **Active**     | Subscription is current and paid | Continue using PineBill normally         |
| **Past Due**   | Payment failed but retrying      | Update payment method in billing portal  |
| **Unpaid**     | Payment overdue, limited access  | Update payment method immediately        |
| **Incomplete** | Payment setup incomplete         | Complete payment setup in billing portal |
| **Canceled**   | Canceled, waiting for period end | Reactivate or continue until period ends |
| **Expired**    | Trial or subscription ended      | Subscribe to continue                    |

<Callout type="warn">
  **Payment Issues**: If your payment fails, you'll have limited time to update your payment method
  before access is restricted.
</Callout>

***

## Common Questions [#common-questions]

<Accordions type="single">
  <Accordion title="Can I upgrade or downgrade anytime?" id="plan-changes">
    **Yes**, but with some differences:

    * **Upgrades**: Take effect immediately. You'll be charged a prorated amount for the remainder of your billing period.
    * **Downgrades**: Scheduled for the end of your current billing period to avoid losing access you've paid for.
    * **Billing cycle changes**: Switching between monthly and annual can be done anytime.
  </Accordion>

  <Accordion title="What happens if I exceed my usage limits?" id="usage-limits">
    **During your billing period:**

    * Monthly limits (invoices, API calls): You'll be prompted to upgrade
    * State limits (members, storage, products): You'll need to upgrade or reduce usage to continue

    **Soft limits**: Some limits allow slight overages with warnings
    **Hard limits**: Others block actions until you upgrade or reduce usage
  </Accordion>

  <Accordion title="Do I get a refund if I cancel?" id="refunds">
    **No**, PineBill follows a no-refund policy:

    * You keep full access until your current billing period ends
    * No charges occur after your period ends
    * You can reactivate anytime before the period ends
  </Accordion>

  <Accordion title="Can I switch between monthly and annual billing?" id="billing-cycle">
    **Yes**, you can switch billing cycles anytime:

    * **Monthly → Annual**: Save money (17-25% discount)
    * **Annual → Monthly**: Takes effect at the end of your annual period
    * Contact support if you need immediate billing cycle changes
  </Accordion>

  <Accordion title="What happens to my data if my subscription expires?" id="data-retention">
    **Your data is safe**:

    * All data (invoices, customers, products) is preserved
    * You can view (but not create) data after expiration
    * Full access resumes immediately when you resubscribe
    * Data is retained for a reasonable period per our data retention policy
  </Accordion>

  <Accordion title="Can I transfer my subscription to another organization?" id="transfer">
    **No**, subscriptions are tied to specific organizations and cannot be transferred. If you need to move to a new organization:

    1. Cancel subscription on old organization
    2. Create new subscription on new organization
    3. Manually migrate your data or contact support for assistance
  </Accordion>
</Accordions>

***

## Related Topics [#related-topics]

* [Organization Settings](/docs/organization/organization-settings) - Manage your organization and team
* [Getting Started](/docs/getting-started) - Set up your account and create your first invoice
* [API Documentation](/docs/api) - Integrate PineBill with your applications


# Troubleshooting (/docs/troubleshooting)





## Troubleshooting [#troubleshooting]

Documentation for troubleshooting is coming soon. This section will cover:

* Common issues and solutions
* FAQ and quick fixes
* How to contact support
* Response times and support channels

If you need immediate assistance, please use the live chat feature in your dashboard or email [support@pinebill.app](mailto:support@pinebill.app).


# File Vault (/docs/vault)







## Quick Start [#quick-start]

File Vault provides secure cloud storage for your business documents, invoices, contracts, and files. Upload, organize, and share files with your team and clients at [Dashboard](/dashboard&#x29; → &#x2A;*[File Vault](/dashboard/vault)**.

<DocImage src="https://storage.pinebill.app/public/docs/image/Files-Vault-PineBill-12-02-2025_09_30_PM.webp" alt="Products page overview" maxHeight="500px" className="w-full p-0" />

***

## What is File Vault? [#what-is-file-vault]

File Vault is PineBill's secure file management system that allows you to:

* **Upload Files**: Store documents, images, PDFs, spreadsheets, and more
* **Organize**: Create folders and subfolders for easy organization
* **Share Securely**: Generate secure sharing links with passwords and expiration
* **Access Control**: Team members can access shared organization files

***

## Storage Limits by Plan [#storage-limits-by-plan]

| Plan           | Storage Capacity | Max File Size | File Retention |
| -------------- | ---------------- | ------------- | -------------- |
| **Trial**      | 100 MB           | 10 MB         | Permanent      |
| **Solo**       | 10 GB            | 10 MB         | Permanent      |
| **Pro**        | 150 GB           | 100 MB        | Permanent      |
| **Enterprise** | 1 TB             | 500 MB        | Permanent      |

<Callout type="info">
  Need more storage? [Upgrade your plan](/docs/subscription) for increased capacity and larger file
  uploads.
</Callout>

***

## Uploading Files [#uploading-files]

<Steps>
  <Step>
    ### 1. Access File Vault [#1-access-file-vault]

    1. Navigate to &#x2A;*[File Vault](/dashboard/vault)**
    2. Click **Upload Files** button
    3. Upload dialog opens
  </Step>

  <Step>
    ### 2. Select Files [#2-select-files]

    * Drag and drop files into the upload area
    * Or click **Browse** to select files from your device
    * Multiple files can be uploaded at once

    **Supported file types:**

    | Category      | File Types              |
    | ------------- | ----------------------- |
    | Documents     | PDF, DOC, DOCX, TXT, MD |
    | Spreadsheets  | XLS, XLSX, CSV          |
    | Presentations | PPT, PPTX               |
    | Images        | JPG, PNG, WEBP, GIF     |
    | Archives      | ZIP                     |
    | Data          | JSON, XML               |
  </Step>

  <Step>
    ### 4. Upload [#4-upload]

    1. Click **Upload** button
    2. Files are encrypted and uploaded securely
    3. Progress bar shows upload status
    4. Files appear in your vault when complete
  </Step>
</Steps>

<Callout type="warn">
  Uploads are limited by your plan's max file size. Files exceeding the limit will be rejected.
</Callout>

***

## File Management [#file-management]

### Viewing Files [#viewing-files]

Files are displayed in a grid or list view with:

* **Thumbnail**: Visual preview (for images and PDFs)
* **Name**: File name and type
* **Size**: File size in KB/MB/GB
* **Uploaded**: Date and uploader
* **Folder**: Current location

### File Actions [#file-actions]

Click on any file to access actions:

* **Download**: Download file to your device
* **Share**: Generate secure sharing link
* **Delete**: Remove file from vault

***

## Searching Files [#searching-files]

Use the search bar to find files quickly:

* **Search by name**: Type file name
* **Filter by type**: PDF, Images, Documents, Spreadsheets
* **Filter by date**: Upload date range
* **Filter by uploader**: Who uploaded the file
* **Filter by folder**: Files in specific folders

***

## Storage Usage [#storage-usage]

<DocImage src="https://storage.pinebill.app/public/docs/image/Files-Vault-PineBill-12-02-2025_09_47_PM.png" alt="Products page overview" maxHeight="500px" className="w-full p-0" />

Monitor your storage usage:

1. Check the storage indicator at the top of File Vault
2. View breakdown by file type
3. See largest files consuming storage
4. Access from &#x2A;*[Subscription Dashboard](/dashboard/subscription)**

**When approaching limit:**

* Yellow warning at 80% usage
* Red alert at 95% usage
* Uploads blocked at 100% capacity

**Solutions:**

* Delete unused files
* Remove old temporary files
* Upgrade to higher plan tier

***

## File Permissions [#file-permissions]

### Organization Files [#organization-files]

All files uploaded to the vault are organization-owned:

* **Admins**: Full access (upload, download, delete, share)
* **Members**: Upload, download, and share files

***

## Related Topics [#related-topics]

* [Organizing Files](/docs/vault/organizing-files) - Folders and file organization
* [Sharing Files](/docs/vault/sharing-files) - Secure file sharing with links
* [Security](/docs/vault/security) - How we keep your files safe
* [Subscription Plans](/docs/subscription) - Storage limits by plan


# Organizing Files (/docs/vault/organizing-files)







## Quick Start [#quick-start]

Organize your files with folders and subfolders for easy access and management. Create a structured filing system that matches your business needs.

***

## Creating Folders [#creating-folders]

<DocImage src="https://storage.pinebill.app/public/docs/image/Files-Vault-PineBill-12-02-2025_09_51_PM.webp" alt="Products page overview" maxHeight="500px" className="w-full p-0" />

<Steps>
  <Step>
    ### 1. Open Create Folder Dialog [#1-open-create-folder-dialog]

    1. Navigate to &#x2A;*[File Vault](/dashboard/vault)**
    2. Click **New Folder** button
    3. Folder creation dialog opens
  </Step>

  <Step>
    ### 2. Name Your Folder [#2-name-your-folder]

    * Enter a descriptive folder name
    * Use clear, searchable names
    * Maximum 255 characters

    **Avoid:**

    * Special characters: `/ \ : * ? " < > |`
    * Very long names that get truncated
  </Step>

  <Step>
    ### 3. Select Location [#3-select-location]

    * **Root**: Create at top level
    * **Inside Folder**: Select parent folder for subfolders
  </Step>

  <Step>
    ### 4. Create [#4-create]

    1. Click **Create Folder**
    2. Folder appears in your vault immediately
    3. Upload files or create subfolders inside
  </Step>
</Steps>

***

## Deleting Folders [#deleting-folders]

### Delete Empty Folder [#delete-empty-folder]

1. Navigate to folder
2. Click folder options menu
3. Select **Delete Folder**
4. Confirm deletion

### Delete Folder with Contents [#delete-folder-with-contents]

**Warning:** Deleting a folder deletes all files and subfolders inside.

1. Click folder options menu
2. Select **Delete Folder**
3. Review contents count
4. Type folder name to confirm
5. Click **Delete Permanently**

**Recovery:**

<Callout type="warning">
  Deleted folders and files cannot be recovered. Ensure you have backups if needed.
</Callout>

***

## Folder Navigation [#folder-navigation]

### Breadcrumb Navigation [#breadcrumb-navigation]

<DocImage src="https://storage.pinebill.app/public/docs/image/Files-Vault-PineBill-12-02-2025_09_55_PM.png" alt="Products page overview" maxHeight="500px" className="w-full p-0" />

Use breadcrumbs at the top to:

* See current location path
* Jump to parent folders
* Return to root quickly

**Example:** Home > Clients > Acme Corp > Invoices

### Quick Actions [#quick-actions]

* **Back Button**: Return to previous folder
* **Search**: Find files across all folders
* **Filter by Folder**: Show files only from specific folders

***

## Folder Structure [#folder-structure]

### Hierarchical Organization [#hierarchical-organization]

Create nested folder structures:

<Files>
  <Folder name="Clients">
    <Folder name="Acme Corp">
      <Folder name="Contracts" />

      <Folder name="Invoices" />

      <Folder name="Communications" />
    </Folder>

    <Folder name="TechStart Inc">
      <Folder name="Proposals" />

      <Folder name="Deliverables" />
    </Folder>

    <Folder name="Global Solutions">
      <Folder name="Projects" />
    </Folder>
  </Folder>
</Files>

### Best Practices [#best-practices]

**By Category:**

<Files>
  <Folder name="Documents" />

  <Folder name="Images" />

  <Folder name="Spreadsheets" />

  <Folder name="Archives" />
</Files>

**By Date:**

<Files>
  <Folder name="2024">
    <Folder name="Q1" />

    <Folder name="Q2" />

    <Folder name="Q3" />

    <Folder name="Q4" />
  </Folder>
</Files>

**By Client/Project:**

<Files>
  <Folder name="Project Alpha">
    <Folder name="Design" />

    <Folder name="Development" />

    <Folder name="Deliverables" />
  </Folder>
</Files>

***

## Related Topics [#related-topics]

* [File Vault](/docs/vault) - Main vault features and uploading
* [Sharing Files](/docs/vault/sharing-files) - Share files and folders securely
* [Security](/docs/vault/security) - File security and encryption


# Security (/docs/vault/security)







## Quick Start [#quick-start]

PineBill File Vault uses enterprise-grade security infrastructure to protect your files at every stage—upload, storage, sharing, and download.

<Callout type="info">
  Your files are protected by the same security standards used by Fortune 500 companies and
  government agencies.
</Callout>

***

## Infrastructure Security [#infrastructure-security]

### Enterprise Cloud Storage [#enterprise-cloud-storage]

Files are stored on globally distributed, enterprise-grade cloud infrastructure:

**Benefits:**

* **99.99% Uptime**: Industry-leading availability
* **Global Distribution**: Fast access from anywhere
* **Automatic Redundancy**: Files replicated across multiple data centers
* **Disaster Recovery**: Built-in backup and failover
* **DDoS Protection**: Network-level threat mitigation

**Storage Architecture:**

* Multi-region redundancy
* Automated failover systems
* Real-time data replication
* Geographic distribution for speed
* Carrier-grade network infrastructure

***

## Encryption [#encryption]

### At Rest [#at-rest]

All files are encrypted when stored:

* **AES-256 Encryption**: Military-grade encryption standard
* **Zero-Knowledge Architecture**: We cannot decrypt your files without authorization

**What this means:**

* Files stored encrypted on disk
* Unreadable if storage is compromised
* Compliant with data protection regulations
* Automatic encryption (no setup required)

### In Transit [#in-transit]

Data encrypted during upload and download:

* **TLS 1.3**: Latest transport security protocol
* **HTTPS Everywhere**: All connections encrypted
* **Perfect Forward Secrecy**: Unique session keys

***

## Sharing Security [#sharing-security]

### Secure Share Links [#secure-share-links]

Share links use multiple security layers:

**Link Security:**

* **Random Tokens**: 128-bit cryptographically secure
* **Unguessable URLs**: Impossible to brute force
* **No Sequential IDs**: Cannot enumerate shares
* **HTTPS Required**: Encrypted transmission

**Access Controls:**

* Time-based expiration
* View count limits
* Password protection
* Instant revocation

### Password Protection [#password-protection]

When sharing with passwords:

* **Hashing**: Industry-standard password hashing
* **Salt Rounds**: Resistant to rainbow tables
* **No Plain Text**: Passwords never stored in plain text
* **Brute Force Protection**: Rate limiting on attempts

***

## Compliance & Privacy [#compliance--privacy]

### Data Protection Standards [#data-protection-standards]

**Data Privacy:**

* No data mining or advertising
* Your files are private
* No third-party data sharing
* Transparent data practices

### Security Certifications [#security-certifications]

### Privacy Guarantees [#privacy-guarantees]

**What we collect:**

* File metadata (name, size, type, dates)
* Upload/access logs for security
* Organization and user information

**What we don't collect:**

* File content analysis
* Personal identification from files
* Behavioral tracking or profiling
* Sale of your data to third parties

***

## Troubleshooting [#troubleshooting]

<Accordions type="single">
  <Accordion title="Suspicious account activity" id="suspicious-activity">
    **Signs of compromise:**

    * Unrecognized logins
    * Files accessed/modified by others
    * Share links you didn't create
    * Password change notifications you didn't initiate

    **Immediate actions:**

    1. Change password immediately
    2. Revoke all active sessions
    3. Check recent activity log
    4. Revoke suspicious share links
    5. Review organization members
    6. Contact support for security review
  </Accordion>

  <Accordion title="File appears corrupted" id="corrupted-file">
    **Problem**: Downloaded file won't open or appears damaged.

    **Possible causes**:

    * Incomplete download
    * Network interruption
    * Disk space issue
    * Original file was corrupted

    **Solution**:

    * Try downloading again
    * Verify file size matches original
    * Check checksum if available
    * Try different browser or device
    * Contact support if issue persists
  </Accordion>

  <Accordion title="Cannot access shared file" id="share-blocked">
    **Problem**: Shared file link is blocked or inaccessible.

    **Possible causes**:

    * Corporate firewall blocking
    * Antivirus software interference
    * Browser security settings
    * Geographic restrictions

    **Solution**:

    * Try different network
    * Disable VPN temporarily
    * Check browser security settings
    * Contact IT if using corporate network
  </Accordion>

  <Accordion title="Storage security concerns" id="security-concerns">
    **Question**: How do I know my files are secure?

    **Answer**: Your files are protected by:

    * Enterprise-grade encryption (AES-256)
    * Secure, SOC 2 Type II certified infrastructure
    * Access controls and authentication
    * Regular security audits
    * Compliance with major data protection regulations

    For additional security requirements, Enterprise plans offer:

    * Advanced encryption options
    * Custom security policies
    * Dedicated security review
    * Enhanced compliance features
  </Accordion>
</Accordions>

***

## Related Topics [#related-topics]

* [File Vault](/docs/vault) - Main vault features
* [Sharing Files](/docs/vault/sharing-files) - Secure file sharing
* [Organization Settings](/docs/organization/organization-settings) - Team access management
* [Subscription Plans](/docs/subscription) - Security features by plan


# Sharing Files (/docs/vault/sharing-files)







## Quick Start [#quick-start]

Share files securely with clients and external parties using time-limited, password-protected sharing links. Control access and track views.

<Callout type="info">
  **Permissions**: Admins and Members can create sharing links. Guests cannot share files
  externally.
</Callout>

***

## Creating Sharing Links [#creating-sharing-links]

<Steps>
  <Step>
    ### 1. Select File to Share [#1-select-file-to-share]

    1. Navigate to &#x2A;*[File Vault](/dashboard/vault)**
    2. Find the file you want to share
    3. Click file menu (three dots)
    4. Select **Share**

    <DocImage src="https://storage.pinebill.app/public/docs/image/Files-Vault-PineBill-12-03-2025_03_07_PM.webp" alt="Products page overview" maxHeight="500px" className="w-full p-0" />
  </Step>

  <Step>
    ### 2. Configure Share Settings [#2-configure-share-settings]

    **Link Expiration:**

    * No expiration (link works forever)
    * 1 hour, 1 day and 7 days
    * Custom date and time

    <DocImage src="https://storage.pinebill.app/public/docs/image/Files-Vault-PineBill-12-03-2025_03_09_PM.webp" alt="Products page overview" maxHeight="500px" className="w-full p-0" />

    **View Limit:**

    * Unlimited views
    * Maximum views (1, 5, 10, 25, 50, 100)
    * Link expires after reaching limit

    **Password Protection:**

    * No password (anyone with link can access)
    * Set password (recipients must enter password to view)
  </Step>

  <Step>
    ### 3. Generate and Copy Link [#3-generate-and-copy-link]

    1. Click **Generate Share Link**
    2. Secure link is created instantly
    3. Copy link to clipboard
    4. Share via email, chat, or any method

    **Link format:**

    ```
    https://pinebill.app/share/abc123xyz789
    ```

    <DocImage src="https://storage.pinebill.app/public/docs/image/Files-Vault-PineBill-12-03-2025_03_13_PM.webp" alt="Products page overview" maxHeight="500px" className="w-full p-0" />
  </Step>

  <Step>
    ### 4. Share with Recipients [#4-share-with-recipients]

    * Send link to intended recipients
    * Include password separately (if set)
    * Inform about expiration time
    * Provide access instructions
  </Step>
</Steps>

***

## Managing Share Links [#managing-share-links]

### Active Shares Dashboard [#active-shares-dashboard]

View all active sharing links:

1. Go to &#x2A;*[File Vault](/dashboard/vault)**
2. Click **Shares** tab
3. See all active shares

<DocImage src="https://storage.pinebill.app/public/docs/image/Files-Vault-PineBill-12-03-2025_03_16_PM.webp" alt="Products page overview" maxHeight="500px" className="w-full p-0" />

**Information shown:**

* File name and size
* Share link (masked)
* Expiration date
* View count (current/maximum)
* Created date and creator
* Last accessed timestamp

### Revoking Share Links [#revoking-share-links]

Immediately disable access:

1. Find share link in Shares dashboard
2. Click **Revoke** or **Delete**
3. Confirm revocation
4. Link stops working instantly

<DocImage src="https://storage.pinebill.app/public/docs/image/Files-Vault-PineBill-12-03-2025_03_18_PM.webp" alt="Products page overview" maxHeight="500px" className="w-full p-0" />

**When to revoke:**

* File was shared by mistake
* Recipient no longer needs access
* Security concern or breach suspected
* File has been updated (create new share)

***

## Security Best Practices [#security-best-practices]

### When Sharing Sensitive Files [#when-sharing-sensitive-files]

**Use Password Protection:**

* Always protect confidential files
* Use strong, unique passwords
* Share password separately

**Set Short Expiration:**

* Don't use "no expiration" for sensitive files
* 1-7 days for most cases
* 1 hour for highly sensitive documents

**Limit Views:**

* Set view count if you know exact recipients
* Prevents unlimited distribution
* Revoke after confirmed access

### Share Link Security [#share-link-security]

**What makes links secure:**

* Unique random tokens (impossible to guess)
* HTTPS encryption in transit
* Server-side access control
* Automatic expiration
* Revocable at any time

**What recipients can do:**

* View file in browser
* Download file (if enabled)
* Cannot see other vault files
* Cannot modify original file

**What recipients cannot do:**

* Access your vault
* View your organization
* Share the file further (no re-sharing)
* See file metadata or history

***

## Limitations [#limitations]

### File Size [#file-size]

Recipients can download files up to your plan's max file size:

* Shared files respect plan limits
* Large files may take time to download
* Consider compressing large files first

### Deleted Files [#deleted-files]

Sharing links for deleted files stop working:

* Restore file from trash to reactivate
* Or create new share link after restoration

***

## Troubleshooting [#troubleshooting]

<Accordions type="single">
  <Accordion title="Share link not working" id="link-broken">
    **Problem**: Recipients get error accessing link.

    **Common causes**:

    * Link expired (check expiration date)
    * View limit reached
    * Link was revoked
    * Wrong password entered
    * File was deleted

    **Solution**: Check share status in dashboard. Create new link if needed.
  </Accordion>

  <Accordion title="Recipient can't download file" id="no-download">
    **Problem**: File opens but can't be downloaded.

    **Solution**:

    * Some browsers block downloads for security
    * Try different browser
    * Disable popup blockers temporarily
    * Use "Save As" or right-click to download
  </Accordion>

  <Accordion title="Lost share link" id="lost-link">
    **Problem**: Can't find previously created share link.

    **Solution**:

    * Check Shares dashboard in vault
    * Search by file name
    * If not found, link may have expired or been revoked
    * Create new share link if needed
  </Accordion>

  <Accordion title="Too many active shares" id="too-many-shares">
    **Problem**: Cannot create more share links.

    **Solution**:

    * Revoke old, unused share links
    * Delete expired shares
    * Upgrade plan for higher limits
    * Check your plan's sharing quota
  </Accordion>
</Accordions>

***

## Related Topics [#related-topics]

* [File Vault](/docs/vault) - Main vault features
* [Security](/docs/vault/security) - How file sharing is secured
* [Organizing Files](/docs/vault/organizing-files) - File organization tips


# Creating Tasks (/docs/tasks/creating-tasks)







## Quick Start [#quick-start]

Go to &#x2A;*[Dashboard](/dashboard)*&#x2A; -> &#x2A;*[Tasks](/dashboard/projects/tasks)** and click **New Task**. You can also create tasks from the Tasks tab on a project detail page.

<DocImage src="https://storage.pinebill.app/public/docs/image/Tasks-PineBill-05-12-2026_04_15_PM.png" alt="Create task dialog" maxHeight="500px" className="w-full p-0" />

***

## Task Fields [#task-fields]

| Field           | Required | Notes                                                          |
| --------------- | -------- | -------------------------------------------------------------- |
| **Title**       | Yes      | Task name, up to 200 characters                                |
| **Description** | No       | Details about the task, up to 1,000 characters                 |
| **Status**      | No       | To Do (default), In Progress, Review, or Done                  |
| **Start Date**  | No       | When the task begins                                           |
| **Due Date**    | No       | Target completion date, shown with urgency colors on the board |
| **Hourly Rate** | No       | Rate used when converting the task to an invoice line item     |
| **Currency**    | No       | Currency for the hourly rate, defaults to USD                  |
| **Notes**       | No       | Internal notes, up to 1,000 characters                         |
| **Project**     | No       | Assign the task to a project                                   |
| **Assigned To** | No       | Team member responsible for the task                           |

***

## Step-by-Step Guide [#step-by-step-guide]

<Steps>
  <Step>
    ### 1. Open the Task Form [#1-open-the-task-form]

    1. Go to &#x2A;*[Tasks](/dashboard/projects/tasks)**
    2. Click **New Task**
    3. Enter a task title
  </Step>

  <Step>
    ### 2. Add Optional Details [#2-add-optional-details]

    Open **More options** to add:

    * Description
    * Status
    * Start and due dates
    * Hourly rate and currency
    * Notes
    * Project
    * Assigned team member

    If you create a task from a project's Tasks tab, the project is automatically selected.

    <DocImage src="https://storage.pinebill.app/public/docs/image/Tasks-PineBill-05-12-2026_04_17_PM.png" alt="Task form with more options expanded" maxHeight="500px" className="w-full p-0" />
  </Step>

  <Step>
    ### 3. Save [#3-save]

    Click **Create Task**. The task appears on the Kanban board in the selected status column (or To Do by default).
  </Step>
</Steps>

***

## Due Date Urgency [#due-date-urgency]

Due dates on task cards are color-coded:

| Color     | Meaning                     |
| --------- | --------------------------- |
| **Red**   | Overdue (past the due date) |
| **Amber** | Due within 2 days           |
| **Gray**  | More than 2 days away       |

***

## Editing a Task [#editing-a-task]

Click a task to open the detail sidebar, then click **Edit**. You can also use the actions menu on the task card. All fields can be updated after creation.

***

## After Creating [#after-creating]

Once a task is saved, you can:

* Start tracking time with the built-in timer
* Upload file attachments (up to 3 files)
* Drag it between Kanban columns to change status
* Convert it to an invoice line item
* Link it to a different project

***

## Related Topics [#related-topics]

* [Task Management](/docs/tasks) - Overview of task features
* [Time Tracking](/docs/tasks/time-tracking) - Track hours with timers
* [Converting Tasks to Invoices](/docs/tasks/task-to-invoice) - Bill for completed work
* [Project Management](/docs/projects) - Organize tasks into projects


# Task Management (/docs/tasks)







## Quick Start [#quick-start]

Use Tasks to break projects into trackable units of work. Each task has a built-in timer for time tracking and can be converted into an invoice line item when the work is done.

Go to &#x2A;*[Dashboard](/dashboard)*&#x2A; -> &#x2A;*[Tasks](/dashboard/projects/tasks)**.

<DocImage src="https://storage.pinebill.app/public/docs/image/Tasks-PineBill-05-12-2026_04_05_PM.png" alt="Tasks page with Kanban board" maxHeight="500px" className="w-full p-2" />

***

## Key Features [#key-features]

<Cards>
  <Card title="Creating Tasks" description="Add tasks with hourly rates, due dates, and team assignment" href="/docs/tasks/creating-tasks" />

  <Card title="Time Tracking" description="Start, pause, and stop timers to log hours automatically" href="/docs/tasks/time-tracking" />

  <Card title="Convert to Invoice" description="Turn completed task hours into invoice line items" href="/docs/tasks/task-to-invoice" />

  <Card title="Project Management" description="Organize tasks inside projects with budgets and timelines" href="/docs/projects" />
</Cards>

***

## View Modes [#view-modes]

Tasks can be displayed in two ways. Use the toggle at the top of the page to switch.

### Kanban Board [#kanban-board]

Drag-and-drop cards between columns to change status. Columns are **To Do**, **In Progress**, **Review**, and **Done**. Each card shows the task title, timer state, time spent, due date, project, and assignee.

<DocImage src="https://storage.pinebill.app/public/docs/image/Tasks-PineBill-05-12-2026_04_05_PM.png" alt="Tasks Kanban board view" maxHeight="450px" className="w-full p-2" />

### Table List [#table-list]

A sortable table with columns for task details. Useful for searching, bulk selecting, and sorting across all tasks.

<DocImage src="https://storage.pinebill.app/public/docs/image/Tasks-PineBill-05-12-2026_04_06_PM.png" alt="Tasks table list view" maxHeight="400px" className="w-full p-2" />

***

## Task Metrics [#task-metrics]

Summary cards at the top of the page show:

* **To Do**: number of tasks not yet started
* **In Progress**: tasks currently being worked on
* **Done**: completed tasks
* **Total**: all tasks across statuses

***

## Task Statuses [#task-statuses]

| Status          | Color | Meaning                       |
| --------------- | ----- | ----------------------------- |
| **To Do**       | Gray  | Not started                   |
| **In Progress** | Blue  | Work is underway              |
| **Review**      | Amber | Work is done, awaiting review |
| **Done**        | Green | Completed                     |

Change status by dragging cards on the Kanban board, using the actions menu, or editing the task.

***

## Searching, Filtering, and Sorting [#searching-filtering-and-sorting]

| Control        | What it does                                                              |
| -------------- | ------------------------------------------------------------------------- |
| **Search**     | Searches task title and description                                       |
| **Status**     | Filters by To Do, In Progress, Review, or Done                            |
| **Sort by**    | Sort by created date, due date, start date, title, status, or hourly rate |
| **Sort order** | Ascending or descending                                                   |

Click **Clear filters** to reset all active filters.

<DocImage src="https://storage.pinebill.app/public/docs/image/Tasks-PineBill-05-12-2026_04_09_PM.png" alt="Task filter bar" maxHeight="150px" className="w-full p-2" />

***

## Task Detail Sidebar [#task-detail-sidebar]

Click any task to open the detail sidebar on the right. From here you can:

* View and edit all task properties
* Start, pause, or stop the timer
* Add or remove time manually with notes
* View timer history with timestamps
* Upload and manage file attachments
* Convert the task to an invoice
* Delete the task

<DocImage src="https://storage.pinebill.app/public/docs/image/Tasks-PineBill-05-12-2026_04_10_PM.png" alt="Task detail sidebar" maxHeight="500px" className="w-full p-2" />

***

## File Attachments [#file-attachments]

You can attach files to a task from the detail sidebar.

| Limit               | Value                                                         |
| ------------------- | ------------------------------------------------------------- |
| **Max files**       | 3 per task                                                    |
| **Max file size**   | 5 MB each                                                     |
| **Supported types** | Images, PDF, Word, Excel, CSV, Markdown, text, JSON, XML, ZIP |

Uploaded files are stored securely. Download links are signed and expire after 1 hour.

***

## Deleting Tasks [#deleting-tasks]

Delete a single task from its actions menu or the detail sidebar. To delete multiple tasks, select them using checkboxes and click **Delete Selected**.

Deleting a task permanently removes it along with all timer history and file attachments. This cannot be undone.

***

## Permissions [#permissions]

| Role            | Can view | Can create | Can edit  | Can delete |
| --------------- | -------- | ---------- | --------- | ---------- |
| **Owner/Admin** | Yes      | Yes        | Any task  | Yes        |
| **Member**      | Yes      | Yes        | Own tasks | No         |

***

## Common Questions [#common-questions]

<Accordions type="single">
  <Accordion title="Can I use tasks without a project?" id="tasks-without-project">
    Yes. The project field is optional. Standalone tasks appear on the main Tasks page and can still use timers and be converted to invoices.
  </Accordion>

  <Accordion title="What happens to a running timer if I close the browser?" id="timer-close-browser">
    The timer keeps running on the server. When you return, the elapsed time since the timer started
    is calculated and displayed. Stop the timer to record the session.
  </Accordion>

  <Accordion title="Can multiple people track time on the same task?" id="multiple-timers">
    Timer sessions are recorded per user. Each team member's time is tracked separately in the timer
    history.
  </Accordion>

  <Accordion title="Is there a limit on how many tasks I can create?" id="task-limit">
    Task limits depend on your subscription plan. You will see a message if you reach your plan's task limit.
  </Accordion>
</Accordions>

***

## Related Topics [#related-topics]

* [Creating Tasks](/docs/tasks/creating-tasks) - Add new tasks
* [Time Tracking](/docs/tasks/time-tracking) - Use timers and manual time entry
* [Converting Tasks to Invoices](/docs/tasks/task-to-invoice) - Bill clients for task hours
* [Project Management](/docs/projects) - Organize tasks into projects


# Converting Tasks to Invoices (/docs/tasks/task-to-invoice)







## Quick Start [#quick-start]

When you finish work on a task, convert it to an invoice to bill your client for the hours tracked.

<DocImage src="https://storage.pinebill.app/public/docs/image/Tasks-PineBill-05-12-2026_04_41_PM.png" alt="Convert task to invoice button" maxHeight="400px" className="w-full p-2" />

***

## Convert a Single Task [#convert-a-single-task]

1. Open the task actions menu or the task detail sidebar
2. Click **Convert to Invoice**
3. PineBill opens the invoice generator with the task added as a line item
4. Add customer details, review the amounts, and finalize the invoice

<DocImage src="https://storage.pinebill.app/public/docs/image/Tasks-PineBill-05-12-2026_04_42_PM.png" alt="Single task conversion to invoice" maxHeight="450px" className="w-full p-2" />

***

## Convert Multiple Tasks [#convert-multiple-tasks]

1. Select tasks using the checkboxes on the Kanban board or table list
2. Click **Convert to Invoice**
3. PineBill opens the invoice generator with each selected task as a separate line item
4. Review all line items, add customer details, and finalize the invoice

<DocImage src="https://storage.pinebill.app/public/docs/image/Tasks-PineBill-05-12-2026_04_44_PM.png" alt="Multiple task conversion to invoice" maxHeight="450px" className="w-full p-2" />

***

## What Gets Included [#what-gets-included]

Each task becomes an invoice line item with:

| Field           | Source                                              |
| --------------- | --------------------------------------------------- |
| **Name**        | Task title, date range, and total duration          |
| **Price**       | Task hourly rate                                    |
| **Quantity**    | Total time spent (used to calculate the line total) |
| **Description** | Task description, if one exists                     |

If the task currency differs from your organization currency, PineBill converts the hourly rate using current exchange rates.

***

## Before Converting [#before-converting]

Make sure the following are in place before converting:

* **Stop all running timers** — Tasks with active timers cannot be converted. Stop the timer first so the final time is recorded.
* **Set an hourly rate** — Tasks without an hourly rate will have a zero price on the invoice line item.
* **Check time entries** — Review the total time spent and make manual adjustments if needed.

***

## After Converting [#after-converting]

* PineBill opens the invoice generator pre-filled with the task line items
* The invoice is saved as a **Draft** — you can edit it before sending
* Once the invoice is created, it is linked to the original tasks via the task's invoice field
* You can view the linked invoice from the task detail sidebar

***

## Common Questions [#common-questions]

<Accordions type="single">
  <Accordion title="Can I convert the same task to multiple invoices?" id="multiple-invoices">
    A task can only be linked to one invoice at a time. To bill for additional work, add more time to the task and convert again, or create a new task.
  </Accordion>

  <Accordion title="What if I don't set an hourly rate?" id="no-rate">
    The line item will have a price of zero. You can edit the price directly in the invoice generator
    before saving.
  </Accordion>

  <Accordion title="Can I remove a task from the invoice after converting?" id="remove-from-invoice">
    Yes. Edit the invoice to remove the line item, or unlink the invoice from the task in the task detail sidebar.
  </Accordion>
</Accordions>

***

## Related Topics [#related-topics]

* [Task Management](/docs/tasks) - Overview of task features
* [Time Tracking](/docs/tasks/time-tracking) - Track hours before invoicing
* [Creating Invoices](/docs/invoices/creating-invoices) - Finalize and send invoices


# Time Tracking (/docs/tasks/time-tracking)







## Quick Start [#quick-start]

Every task has a built-in timer. Click the play button on any task card or open the task detail sidebar to start tracking time.

<DocImage src="https://storage.pinebill.app/public/docs/image/Tasks-PineBill-05-12-2026_04_20_PM.png" alt="Task with running timer" maxHeight="400px" className="w-full p-2" />

***

## Timer Controls [#timer-controls]

| Action     | Button | What it does                                            |
| ---------- | ------ | ------------------------------------------------------- |
| **Start**  | Play   | Begins tracking time from zero                          |
| **Pause**  | Pause  | Temporarily pauses the timer, can be resumed            |
| **Resume** | Play   | Continues a paused timer from where it stopped          |
| **Stop**   | Stop   | Ends the session and adds the elapsed time to the total |

When you start or resume a timer, the task status automatically changes to **In Progress**.

The timer displays elapsed time in **HH:MM:SS** format and updates every second. A pulsing indicator shows when a timer is actively running.

<DocImage src="https://storage.pinebill.app/public/docs/image/Tasks-PineBill-05-12-2026_04_20_PM.png" alt="Timer control buttons on task card" maxHeight="300px" className="w-full p-2" />

***

## Typical Timer Workflow [#typical-timer-workflow]

1. Open a task and click **Start** to begin tracking
2. Work on the task — the timer runs in the background
3. Click **Pause** if you need a break, then **Resume** to continue
4. Click **Stop** when the work session is finished
5. The elapsed time is added to the task's total time spent

You can run multiple sessions across different days. Each session is recorded separately in the timer history.

***

## Manual Time Adjustments [#manual-time-adjustments]

If you forgot to start the timer or need to correct logged time, use the manual adjustment dialog in the task detail sidebar.

### Adding Time [#adding-time]

1. Open the task detail sidebar
2. Click the manual time adjustment button
3. Enter the duration to add
4. Optionally add a note explaining why
5. Click **Add**

### Removing Time [#removing-time]

1. Open the task detail sidebar
2. Click the manual time adjustment button
3. Enter the duration to remove
4. Optionally add a note explaining why
5. Click **Remove**

The total time spent cannot go below zero.

<DocImage src="https://storage.pinebill.app/public/docs/image/Tasks-PineBill-05-12-2026_04_34_PM.png" alt="Manual time adjustment dialog" maxHeight="400px" className="w-full p-2" />

***

## Timer History [#timer-history]

The task detail sidebar shows a complete log of all timer sessions, including:

* Action type (Start, Stop, Pause, Resume, Manual Add, Manual Remove)
* Duration recorded
* User who performed the action
* Timestamp
* Notes (for manual adjustments)

Sessions are listed in reverse chronological order.

<DocImage src="https://storage.pinebill.app/public/docs/image/Tasks-PineBill-05-12-2026_04_39_PM.png" alt="Timer session history" maxHeight="400px" className="w-full p-2" />

***

## How Time is Calculated [#how-time-is-calculated]

* **Start/Resume** records the moment the timer begins
* **Stop/Pause** calculates elapsed seconds since the last start or resume
* **Manual Add** adds the specified seconds directly to the total
* **Manual Remove** subtracts the specified seconds from the total
* The task's **total time spent** is the cumulative sum of all sessions

If you close the browser while a timer is running, the server continues tracking. The elapsed time is calculated when you return and stop the timer.

***

## Common Questions [#common-questions]

<Accordions type="single">
  <Accordion title="Can I edit a past timer session?" id="edit-session">
    Past sessions cannot be edited directly. Use manual time adjustments to add or remove time and include a note for context.
  </Accordion>

  <Accordion title="Does the timer stop if my computer goes to sleep?" id="computer-sleep">
    The timer start time is recorded on the server. Even if your computer sleeps, the full elapsed
    time is calculated when you stop the timer.
  </Accordion>

  <Accordion title="Can I track time without setting an hourly rate?" id="no-hourly-rate">
    Yes. The timer works regardless of whether an hourly rate is set. The hourly rate is only used when converting a task to an invoice line item.
  </Accordion>
</Accordions>

***

## Related Topics [#related-topics]

* [Task Management](/docs/tasks) - Overview of task features
* [Creating Tasks](/docs/tasks/creating-tasks) - Set up tasks with hourly rates
* [Converting Tasks to Invoices](/docs/tasks/task-to-invoice) - Bill clients for tracked hours