# Introduction (/docs)



## Welcome to PineBill

PineBill is a comprehensive invoice generation and management platform designed to help businesses of all sizes create professional invoices, manage customers, track products, and monitor payments efficiently. Whether you're a freelancer, small business, or growing enterprise, PineBill provides the tools you need to streamline your invoicing workflow.

## What You Can Do with PineBill

### Core Features

* **Professional Invoice Templates**: Choose from beautifully designed invoice templates (Regular, Bold Professional and more...) that can be customized with your company branding
* **Smart Invoice Generation**: Create invoices quickly with support for product-based and hourly billing modes, automatic calculations for taxes, discounts, and shipping
* **Customer Management**: Build and maintain a comprehensive customer database with contact information, addresses, and timezone support
* **Product Catalog**: Organize your products and services with categories, SKUs, pricing, and photos for quick invoice creation
* **Multi-currency Support**: Generate invoices in any currency with automatic exchange rate tracking and conversion
* **Secure Invoice Sharing**: Share invoices with customers via password-protected links with expiration dates and view limits
* **Payment Tracking**: Monitor invoice statuses (Draft, Sent, Paid, Overdue, Cancelled) and track payment history
* **Team Collaboration**: Invite team members with role-based permissions (Admin, Member, Guest) and assign invoices to employees
* **Business Analytics**: Track revenue, product performance, and customer growth with visual charts and reports
* **File Vault**: Securely store and share files with your organization using S3-compatible cloud storage
* **API Integration**: Integrate PineBill with your applications using our comprehensive REST API

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

Explore our comprehensive documentation to make the most of PineBill:

### 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="text-primary" />} />

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

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

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

### Advanced Features

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

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

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

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

### Integration & Support

<Cards>
  <Card title="Advanced Features" description="API integration, webhooks, custom fields, and advanced configurations" href="/docs/advanced" icon={<SettingsIcon className="text-primary" />} />

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

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

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

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 transform the way you manage invoices!


# Analytics (/docs/analytics)



## Quick Start

Analytics provides insights into your business performance. Access it from **[Dashboard](/dashboard)** → **[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

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

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

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

* 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

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

### 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 charts require a **Pro** or **Enterprise** subscription.

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

Line chart showing customer acquisition:

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

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

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

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

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

***

## Enterprise Analytics (Enterprise Plan)

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

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

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)

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

### Multi-Currency Support

Analytics automatically handles multiple currencies:

* All invoices 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

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

If no data exists for the selected period:

* Charts show "No data available" message
* Metric cards show zero values
* Create invoices to start seeing analytics

### Subscription Limits

**Basic Plan:**

* 4 metric cards only
* No charts

**Pro Plan:**

* All basic metrics
* 6 advanced charts
* Product analytics

**Enterprise Plan:**

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

***

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

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


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



import { Accordion, Accordions } from "fumadocs-ui/components/accordion";

## Quick Start

Adding customers to PineBill is straightforward. Navigate to the **[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-12-01-2025_11_35_AM.webp" alt="Invoice Generator Overview" maxHeight="500px" className="w-full p-0" />

## 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")      |
| 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

### 1. Access the Customer Creation Form

1. Navigate to **[Dashboard](/dashboard)** → **[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

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

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

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

* 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

<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

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

Navigate to **[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

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

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                           |

**Sample CSV:**

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

***

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

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

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

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

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

***

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

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

| 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            |
| **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

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

<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

| 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

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

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

<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

**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

* 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

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

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

* [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)



import { Accordion, Accordions } from "fumadocs-ui/components/accordion";

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

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

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

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

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)                   |
| Timezone      | Yes      | Update timezone (IANA format)                                              |
| Description   | Yes      | Modify internal notes and customer details                                 |

## Additional Notes

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

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


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



import { Accordion, Accordions } from "fumadocs-ui/components/accordion";

## 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 at [Dashboard](/dashboard) → Audit → **[API Logs](/dashboard/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/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?

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

### Accessing the Logs Dashboard

1. Navigate to **[API Logs](/dashboard/api-logs)**
2. View recent API requests in chronological order
3. Use filters to narrow down results

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

API logs include HTTP status codes indicating request outcomes:

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

| 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)

| 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

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

**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

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

<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

* [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)



import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
import { Step, Steps } from "fumadocs-ui/components/steps";

## Quick Start

API keys provide secure authentication for programmatic access to PineBill. Manage your API keys at Dashboard → **[API Keys](/dashboard/api-keys)**.

<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

<Steps>
  <Step>
    ### 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. Navigate to **[API Keys](/dashboard/api-keys)**
    2. Click **Create API Key** button
    3. 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

    * 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

    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

PineBill API keys follow this format:

```
pb_1234567890abcdefghijklmnopqrstuv
```

**Structure:**

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

***

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

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

```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
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

<Steps>
  <Step>
    ### 1. Access API Keys Dashboard

    1. Go to **[API Keys](/dashboard/api-keys)**
    2. Find the key to revoke
    3. 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

    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

### Usage Statistics

View detailed usage for each API key:

1. Navigate to **[API Keys](/dashboard/api-keys)**
2. Click on a key to view details
3. 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

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

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

***

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

* [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)



import { Step, Steps } from "fumadocs-ui/components/steps";

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

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

***

## Getting Started

<Steps>
  <Step>
    ### 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

    1. Navigate to **[API Keys](/dashboard/api-keys)**
    2. Click **Create API Key**
    3. 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/My-Organization-12-02-2025_08_50_PM.webp" alt="Invoice Generator Overview" maxHeight="400px" className="w-full p-0" />
  </Step>

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

    Visit **[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

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

Requests are rate-limited based on your subscription:

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

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

<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

### Documentation

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

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

* [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


# Employees (/docs/employees)



import { Step, Steps } from "fumadocs-ui/components/steps";
import { Accordion, Accordions } from "fumadocs-ui/components/accordion";

## Quick Start

Employees represent your organization's staff members. Track who creates invoices and analyze employee performance in analytics. Access from **[Dashboard](/dashboard)** → **[Employees](/dashboard/organization/employees)**.

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

***

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

<Steps>
  <Step>
    ### Open Create Dialog

    1. Navigate to **[Employees](/dashboard/organization/employees)** page
    2. Click **Add Employee** button (top-right)
    3. 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

    **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

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

***

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

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

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

**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

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

**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

<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

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


# Creating Your Account (/docs/getting-started/create-account)



import { Step, Steps } from "fumadocs-ui/components/steps";
import { Accordion, Accordions } from "fumadocs-ui/components/accordion";

## Overview

Sign up using email and password or Google OAuth for instant access.

<img alt="Account Creation Screenshot" src="https://storage.pinebill.app/public/docs/image/docs-auth.png" width="1269" height="801" />

## Sign Up Methods

### Email and Password

<Steps>
  <Step>
    ### Sign Up Page

    Visit [pinebill.app/auth/signup](/auth/signup)
  </Step>

  <Step>
    ### Enter Information

    * Email address
    * Password (see requirements below)
    * Confirm password
  </Step>

  <Step>
    ### Submit

    Click "Sign Up" to create your account
  </Step>
</Steps>

### Google OAuth

<Steps>
  <Step>
    ### Click "Sign up with Google"

    On the sign-up page
  </Step>

  <Step>
    ### Choose Account & Authorize

    Select your Google account and grant permissions
  </Step>
</Steps>

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

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

You'll be guided through organization setup and land on your dashboard with prompts to add customers, products, and create invoices.

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

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)



import { Step, Steps } from "fumadocs-ui/components/steps";
import { Accordion, Accordions } from "fumadocs-ui/components/accordion";

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

> * 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

<Steps>
  <Step>
    ### 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/invoice-intro-1.png" alt="First Invoice Screenshot" maxHeight="350px" className="mobile:w-full w-[50%]" />
  </Step>

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

    **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)

    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)

    Enter discount amount (applied to subtotal before tax).
  </Step>

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

    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

    * **Issued Date**: Defaults to today
    * **Due Date**: When payment is expected (use date picker or shortcuts like "Net 30")
  </Step>

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

    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

    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

    **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

<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?

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

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

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

We recommend following this path for the best onboarding experience:

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

Familiarize yourself with [PineBill's interface](/docs/getting-started/understanding-interface) to navigate efficiently.

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

Follow our [complete tutorial](/docs/getting-started/first-invoice) to generate your first professional invoice.

### Step 5: Customize Settings (5 minutes)

Configure [invoice settings](/docs/invoices/invoice-settings) to match your business needs.

## Key Features at a Glance

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

Build your customer database with:

* Contact information and addresses
* Unique customer identifiers
* Timezone support for global clients
* Customer history and invoice tracking

### Product Catalog

Organize your offerings with:

* Product categories and photos
* SKU/model number tracking
* Pricing management
* Active/inactive status control

### Payment Processing

Monitor your business with:

* Invoice status tracking (Draft, Sent, Paid, Overdue, Cancelled)
* Payment date recording
* Multi-currency support
* Revenue analytics

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



import { Step, Steps } from "fumadocs-ui/components/steps";
import { Accordion, Accordions } from "fumadocs-ui/components/accordion";

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

<Steps>
  <Step>
    ### Welcome & Organization Name

    Enter your business name and business email address,
  </Step>

  <Step>
    ### Company Information (Optional)

    Add phone number and full address,
  </Step>

  <Step>
    ### Default Settings (Optional)

    Choose currency and timezone,
  </Step>

  <Step>
    ### Company Logo (Optional)

    Upload your logo for invoice branding.
  </Step>

  <Step>
    ### Complete Setup

    Review and finish.
  </Step>
</Steps>

## Configuration Details

### Company Name

Use your official business name as it appears on invoices and emails throughout the platform.

### Company Address

Enter your business address with street, city, state/province, postal code, and country. This appears on all invoices.

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

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

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

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

To update settings: Click profile icon → "Organization Settings" → "Company Settings" → Edit → Save.

## Troubleshooting

<Accordions type="single">
  <Accordion title="Logo won't upload" id="logo-wont-upload">
    Check file format (PNG/JPG/WebP), size (under 5 MB), clear cache, or try different browser
  </Accordion>

  <Accordion title="Settings not saving" id="settings-not-saving">
    Ensure you click "Save", check browser console for errors, disable extensions
  </Accordion>

  <Accordion title="Timezone incorrect" id="timezone-incorrect">
    Search for different city in same timezone, verify UTC offset
  </Accordion>
</Accordions>


# Creating Invoices (/docs/invoices/creating-invoices)



## Quick Start

Access the invoice generator from your dashboard by clicking "Create Invoice" or navigating to the Generator page.

<DocImage src="https://storage.pinebill.app/public/docs/image/ic-intro.webp" alt="Invoice Generator Overview" maxHeight="500px" className="w-full p-0" />

***

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

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

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

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

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

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

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

Add items to your invoice:

* **[Option A: From Product List](/docs/products/product-selection)**: Select saved products or services
* **[Option B: Temporary Items](/docs/products/adding-products#temporary-products)**: Create one-time items directly

<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:

* **Drag to Reorder**: Click and drag items to change order
* **Inline Editing**: Click to edit quantity and unit price directly

<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

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)

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

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).
* **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

Select one or more payment methods from your saved payment methods list. Payment methods are ***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

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

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

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

```
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

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

* [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


# Editing Invoices (/docs/invoices/editing-invoices)



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

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

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

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

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

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

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

| 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

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

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

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

You can assign or change the employee responsible for an invoice directly from the details page.

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

* 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

* [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)



import { Accordion, Accordions } from "fumadocs-ui/components/accordion";

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

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

PineBill supports two invoicing modes to match your business model:

<Tabs items={['Product', 'Hourly']}>
  <Tab value="Product">
    ### 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

    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

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

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

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

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

<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

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

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

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

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

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

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

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

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

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

* [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

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

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

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

| 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

* **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

This section displays all line items and the calculation breakdown.

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

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

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

Track which team member is responsible for this invoice. This is useful for analyzing employee performance and tracking sales.

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

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

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

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

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

<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

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

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

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

**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

* [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

Access all your invoices from the Invoices page with powerful search and filtering capabilities.

## List View Features

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

| 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

| 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

Find invoices quickly with powerful filters:

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

| 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

| 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

| 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

| 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

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

| 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

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

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

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>

## 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
* Clear all filters to start fresh


# Invoice Settings (/docs/invoices/invoice-settings)



import { Accordion, Accordions } from "fumadocs-ui/components/accordion";

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

1. Click **Invoices** in the sidebar
2. Click **Invoice Settings**
3. Click the **Edit Settings** button (owners only)

<DocImage src="https://storage.pinebill.app/public/docs/image/Invoice-Settings-PineBill-12-01-2025_09_30_AM.webp" alt="Invoice Settings Page Overview" maxHeight="350px" className="w-[95%] p-0" />

***

## Invoice Number Generation

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

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

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

**Requirements:**

* 3-10 characters
* Examples: `INV`, `BILL`, `ORG`

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

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

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

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

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

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

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

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

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

<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)



import { Accordion, Accordions } from "fumadocs-ui/components/accordion";

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

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

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

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

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

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

Create shareable links for your invoices with customizable security options.

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

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

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

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

View and manage all your share links in one place.

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

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

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

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

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

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

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

* **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

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

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

| 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

<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

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

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

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

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

**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

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

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

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

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

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

| 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

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

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                     |


# Organization (/docs/organization)



## Quick Start

The Organization page shows your company information and team members. Access it from **[Dashboard](/dashboard)** → **[Organization](/dashboard/organization)**.

<DocImage src="https://storage.pinebill.app/public/docs/image/Organizations-12-01-2025_09_11_PM.webp" alt="Organization overview page" maxHeight="500px" className="w-full p-0" />

***

## Company Information

The top card displays your company details:

### Company Logo

* Displays uploaded company logo (if set)
* 96x96px preview
* Set in [Organization Settings](/dashboard/organization/settings)

### 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 with copy button                    |

### Organization ID

* Unique identifier for your organization
* Used for API integrations and support
* Click the copy button to copy to clipboard

***

## Team Members

Team member management appears below company information.

**Note**: Solo plan users cannot add team members. This feature requires Pro or Enterprise plans.

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

| Role       | Permissions                                                 |
| ---------- | ----------------------------------------------------------- |
| **ADMIN**  | Full access. Can manage organization, members, and all data |
| **MEMBER** | Can create and manage invoices, customers, products         |

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

**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

Click the **Settings** button (top-right) to access [Organization Settings](/dashboard/organization/settings) where you can edit company information and manage logo.

***

## Related Topics

* [Organization Settings](/docs/organization/organization-settings) - Edit company details
* [Subscription Plans](/docs/subscription) - Upgrade to add team members


# Organization Settings (/docs/organization/organization-settings)



import { Step, Steps } from "fumadocs-ui/components/steps";
import { Accordion, Accordions } from "fumadocs-ui/components/accordion";

## Quick Start

Organization Settings allows owners to edit company details and branding. Access it from **[Organization](/dashboard/organization)** → **Settings** button or directly at **[Settings](/dashboard/organization/settings)**.

<DocImage src="https://storage.pinebill.app/public/docs/image/Organizations-12-01-2025_09_20_PM.webp" alt="Organization settings overview" maxHeight="500px" className="w-full p-0" />

**Permissions**: Only organization owners can edit settings. Members and guests can view but not modify.

***

## Editing Company Information

<Steps>
  <Step>
    ### Click Edit Button

    1. Navigate to Organization Settings
    2. Find the "Company Information" card
    3. Click the **Edit** button (top-right of card)
    4. Form fields become editable
  </Step>

  <Step>
    ### 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) |

    **All fields are optional** - leave blank if not needed.
  </Step>

  <Step>
    ### Save Changes

    1. Click **Save Organization Settings** button
    2. Changes are saved
    3. Form exits edit mode
    4. Success notification appears

    **Cancel**: Click **Cancel** button to discard changes and reset form.
  </Step>
</Steps>

***

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

<DocImage src="https://storage.pinebill.app/public/docs/image/Organizations-12-01-2025_09_23_PM.png" alt="Company logo upload interface" maxHeight="400px" className="w-full px-4" />

### Logo Preview

* 128x128px preview shown
* Current logo displays if set
* "No logo" placeholder if not set

***

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

### 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 (Pro+ Only)

**Available on**: Pro and Enterprise plans

**Features:**

* Faster response times
* Live chat support
* Priority assistance

Click **Contact Live Support** to open live chat.

<DocImage src="https://storage.pinebill.app/public/docs/image/Organizations-12-01-2025_09_25_PM.png" alt="Priority support card for Pro users" maxHeight="300px" className="w-full p-0" />

***

## Permission Notes

### Owner-Only Actions

Only organization owners can:

* Edit company information
* Upload/delete company logo
* Change default currency
* Update timezone

***

## Common Errors

<Accordions type="single">
  <Accordion title="Company name is required" id="name-required">
    **Problem**: Company name field cannot be empty if other fields are filled.

    **Solution**: Enter a company name or leave all fields empty.
  </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>
</Accordions>

***

## Related Topics

* [Organization Overview](/docs/organization) - View organization details
* [Creating Invoices](/docs/invoices/creating-invoices) - Company info appears on invoices
* [Subscription Plans](/docs/subscription) - Upgrade for more features


# Payment Methods (/docs/payments)



import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
import { Step, Steps } from "fumadocs-ui/components/steps";

## Quick Start

Payment methods are displayed on invoices to show customers how they can pay. Navigate to **[Payment Methods](/dashboard/payment-methods)** to manage your payment options.

<DocImage src="https://storage.pinebill.app/public/docs/image/Manage-Payments-PineBill-12-01-2025_08_38_PM.webp" alt="Payment methods list page" maxHeight="500px" className="w-full p-0" />

***

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

<Steps>
  <Step>
    ### 1. Open Create Dialog

    1. Navigate to **[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

    **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

    **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

    1. Click **Create Payment Method**
    2. Payment method is saved
    3. Available for use in invoices
  </Step>
</Steps>

***

## Using Payment Methods in 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

* Invoices can have multiple payment methods
* All selected methods appear on the PDF
* Customers can choose their preferred option

### 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 support unlimited label-value 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

1. Edit the custom payment method
2. Add, remove, or modify field labels and values
3. Save changes

***

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

* [Creating Invoices](/docs/invoices/creating-invoices) - Add payment methods to invoices
* [Invoice Settings](/docs/invoices/invoice-settings) - Configure default payment methods


# Adding New Products (/docs/products/adding-products)



import { Accordion, Accordions } from "fumadocs-ui/components/accordion";

## Quick Start

Navigate to the **[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-12-01-2025_08_05_PM.webp" alt="Products page overview" maxHeight="500px" className="w-full p-0" />

***

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

| 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 selection dialogs   |
| 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

### Step 1: Open Product Dialog

1. Navigate to **[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

**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)

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 invoice selection dialogs

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

The **Active Product** checkbox controls visibility:

* **Checked** (default): Product appears in invoice creation product selector
* **Unchecked**: Product hidden from selection but remains in catalog

***

## Temporary Products

Temporary products are created during invoice generation and are NOT saved to your catalog.

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

1. During invoice creation, in the **Products** tab
2. Click **Add Temporary** button
3. Fill in:
   * Name \*
   * Model (optional)
   * Price \*
   * Description (optional)
4. Click **Add to Invoice**
5. Product is added to invoice but not saved to catalog

<DocImage src="https://storage.pinebill.app/public/docs/image/Create-Invoice-PineBill-12-01-2025_08_27_PM.webp" alt="Add temporary product form" maxHeight="400px" className="w-full p-0" />

**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

<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

* [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

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

Navigate to **[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

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

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

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

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

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

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

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

* [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

Product categories help you organize your products into logical groups. Access categories from the **[Products](/dashboard/products)** page or create them 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

| 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

### Method 1: From Products Page

1. Navigate to **[Products](/dashboard/products)** page
2. Click the category filter dropdown
3. Select "Manage Categories" option
4. Click "Create Category" button
5. Fill in category details
6. Click "Create Category" to save

<DocImage src="https://storage.pinebill.app/public/docs/image/Product-Categories-List-PineBill-12-01-2025_07_54_PM.webp" alt="Products page showing category filtering" maxHeight="500px" className="w-full p-0" />

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

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

1. Navigate to Products page → Category filter → "Manage Categories"
2. Find the category in the list
3. Click the edit icon
4. Update category details
5. Click "Save Changes"

**Editable fields:**

* Name
* Description
* Color
* Active status

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

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. Navigate to category management
3. Click delete icon
4. Confirm deletion

***

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



import { Accordion, Accordions } from "fumadocs-ui/components/accordion";

## Quick Start

Product Properties allow you to define custom attributes for your products beyond the standard fields. Navigate to **[Product Properties](/dashboard/properties)** to create property 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?

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

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

| 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

### Step 1: Navigate to Properties Page

1. Go to **[Product Properties](/dashboard/properties)**
2. Click the **New Property** button (top-right)
3. The property creation dialog will open

<DocImage src="https://storage.pinebill.app/public/docs/image/Product-Properties-PineBill-01-30-2026_09_41_AM.png" alt="Products Properties Page" maxHeight="500px" className="w-full p-0" />

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

Click **Create Property** to save. The property will immediately be available for assignment to products.

***

## Managing Property Definitions

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

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

* 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

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

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

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

Properties marked as required will show:

* An asterisk (\*) next to the label
* Validation error if left empty when saving

***

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

| 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

<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 **[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

<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

* [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


# Subscription (/docs/subscription)



import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
import { Step, Steps } from "fumadocs-ui/components/steps";

## Quick Start

Every PineBill account starts with a **7-day free trial** of Pro features. View and manage your subscription at **[Subscription Dashboard](/dashboard/subscription)**.

<DocImage src="https://storage.pinebill.app/public/docs/image/Dashboard-PineBill-12-02-2025_08_35_PM (1).webp" alt="Products page overview" maxHeight="500px" className="w-full p-0" />

***

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

Each plan includes specific usage limits tracked in your dashboard:

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

* **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

<Steps>
  <Step>
    ### 1. Access Plan Management

    1. Navigate to **[Subscription Dashboard](/dashboard/subscription)**
    2. Click **Upgrade Now** or **Change Plan** button
    3. Plan comparison dialog opens
  </Step>

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

    * 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 Portal

Access your billing portal to manage:

* View invoices and payment history
* Update payment methods
* Change billing email
* Download receipts

**To access**: Click **Billing Portal** button on the Subscription Dashboard (opens in 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

* **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

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

<Steps>
  <Step>
    ### 1. Initiate Cancellation

    1. Go to **[Subscription Dashboard](/dashboard/subscription)**
    2. Click **Cancel Subscription** in the Management section
    3. Cancellation dialog opens
  </Step>

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

    * 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

Changed your mind? You can reactivate anytime before your period ends:

1. Go to **[Subscription Dashboard](/dashboard/subscription)**
2. Click **Reactivate** button
3. Subscription continues without interruption

***

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

<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

* [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

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)



import { Step, Steps } from "fumadocs-ui/components/steps";

## 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) → **[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?

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

| 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

<Steps>
  <Step>
    ### 1. Access File Vault

    1. Navigate to **[File Vault](/dashboard/vault)**
    2. Click **Upload Files** button
    3. Upload dialog opens
  </Step>

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

    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

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

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

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

<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 **[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

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

* [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)



import { Step, Steps } from "fumadocs-ui/components/steps";
import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
import { File, Folder, Files } from "fumadocs-ui/components/files";

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

<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. Navigate to **[File Vault](/dashboard/vault)**
    2. Click **New Folder** button
    3. Folder creation dialog opens
  </Step>

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

    * **Root**: Create at top level
    * **Inside Folder**: Select parent folder for subfolders
  </Step>

  <Step>
    ### 4. Create

    1. Click **Create Folder**
    2. Folder appears in your vault immediately
    3. Upload files or create subfolders inside
  </Step>
</Steps>

***

## Deleting Folders

### Delete Empty Folder

1. Navigate to folder
2. Click folder options menu
3. Select **Delete Folder**
4. Confirm deletion

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

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

* **Back Button**: Return to previous folder
* **Search**: Find files across all folders
* **Filter by Folder**: Show files only from specific folders

***

## Folder Structure

### Hierarchical Organization

Create nested folder structures:

<Files>
  <Folder name="Clients" defaultOpen>
    <Folder name="Acme Corp" defaultOpen>
      <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

**By Category:**

<Files>
  <Folder name="Documents" />

  <Folder name="Images" />

  <Folder name="Spreadsheets" />

  <Folder name="Archives" />
</Files>

**By Date:**

<Files>
  <Folder name="2024" defaultOpen>
    <Folder name="Q1" />

    <Folder name="Q2" />

    <Folder name="Q3" />

    <Folder name="Q4" />
  </Folder>
</Files>

**By Client/Project:**

<Files>
  <Folder name="Project Alpha" defaultOpen>
    <Folder name="Design" />

    <Folder name="Development" />

    <Folder name="Deliverables" />
  </Folder>
</Files>

***

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



import { Accordion, Accordions } from "fumadocs-ui/components/accordion";

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

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

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

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

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

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

### Data Protection Standards

**Data Privacy:**

* No data mining or advertising
* Your files are private
* No third-party data sharing
* Transparent data practices

### Security Certifications

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

<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

* [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)



import { Step, Steps } from "fumadocs-ui/components/steps";
import { Accordion, Accordions } from "fumadocs-ui/components/accordion";

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

<Steps>
  <Step>
    ### 1. Select File to Share

    1. Navigate to **[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

    **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

    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

    * Send link to intended recipients
    * Include password separately (if set)
    * Inform about expiration time
    * Provide access instructions
  </Step>
</Steps>

***

## Managing Share Links

### Active Shares Dashboard

View all active sharing links:

1. Go to **[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

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

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

**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

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

Sharing links for deleted files stop working:

* Restore file from trash to reactivate
* Or create new share link after restoration

***

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

* [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