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

# Invoicing

> Create, update and query invoices using Model Context Protocol tools

## Overview

Tight Invoicing MCP tools enable AI assistants and agents to search, review, and manage invoices. Users can find invoices by customer, status, or amount, create new invoices with line items and payment plans, and update existing invoices, all through conversational AI interactions.

With these tools, you can build AI-powered invoicing experiences where users ask questions like "Show me all overdue invoices" or "Create an invoice for my client with a payment plan."

## Available Tools

### Query Invoices

The `query_invoices` tool searches for invoices based on multiple criteria. You can filter by customer, amount, date, invoice number, status, line items, payment plans, outstanding balance, and more.

<Accordion title="Parameters">
  <ParamField path="customer" type="string">
    Search for invoices by specific customer
  </ParamField>

  <ParamField path="amount" type="number | range">
    Search on total invoice amount or within an amount range (e.g., "\$500-\$2000")
  </ParamField>

  <ParamField path="date" type="date | date range">
    Filter invoices by invoice date or date range (e.g., "last quarter", "January 2025", "2025-01-01 to 2025-03-31")
  </ParamField>

  <ParamField path="dueDate" type="date | date range">
    Filter invoices by due date or date range to find upcoming or past due payments
  </ParamField>

  <ParamField path="name" type="string">
    Search by specific invoice number or invoice full invoice name
  </ParamField>

  <ParamField path="status" type="string">
    Filter by invoice status: Draft, Sent, Paid, Overdue, Partially Paid, or Void
  </ParamField>

  <ParamField path="lineItems" type="string">
    Search for invoices containing specific services or expenses in line item descriptions
  </ParamField>

  <ParamField path="installments" type="boolean">
    Filter invoices that have payment plans
  </ParamField>

  <ParamField path="balance" type="number | range">
    Search for invoices with specific outstanding balance amounts or ranges (e.g., "\$100-\$1000")
  </ParamField>

  <ParamField path="description" type="string">
    Fuzzy search for text in line item descriptions or invoice notes
  </ParamField>
</Accordion>

<Tip>
  You can combine multiple search criteria to narrow results. For example, search for "overdue invoices over \$1,000 from customer ABC Corp" by combining status, amount, and customer filters.
</Tip>

### Get Invoice Details

The `get_invoice` tool retrieves detailed information about a specific invoice. Use this tool to review invoice details before making updates or to discuss pricing and payment terms with the user.

This tool returns comprehensive invoice data including:

* Customer information and contact details
* Invoice date, due date, and invoice number
* Line items with descriptions, quantities, rates, and amounts
* Service items and reimbursable expense items
* Sales tax calculations per line item
* Installment schedules and dates
* Payment history and current status
* Outstanding balance
* Discounts applied (percentage or fixed amount)
* Invoice notes, terms, and payment instructions

<Note>
  This tool is essential for conversational workflows where users want to discuss a specific invoice with the AI before making changes. The detailed context helps the AI provide informed suggestions about pricing, payment terms, or modifications.
</Note>

### Save Invoice

The `save_invoice` tool creates new invoices or updates existing ones. This is the primary tool for managing invoices, adding line items, setting up payment plans, applying discounts, and managing invoice status.

<Accordion title="Parameters">
  <ParamField path="customer" type="string">
    Assign or change the invoice customer by name or ID
  </ParamField>

  <ParamField path="lineItems" type="array">
    Add, modify, or remove line items. Each line item includes:

    * **description**: Description of the service or product
    * **quantity**: Number of units
    * **rate**: Price per unit
    * **amount**: Total line item amount (quantity × rate)
    * **expense** (optional): Reference to an expense for reimbursement
    * **salesTaxPercentage** (optional): Sales tax percentage for this line item
  </ParamField>

  <ParamField path="installments" type="object">
    Set up or modify payment schedules breaking the total into installments. Each installment includes an amount and date.
  </ParamField>

  <ParamField path="date" type="date">
    Invoice date displayed on the invoice; also used for double-entry accounting purposes
  </ParamField>

  <ParamField path="dueDate" type="date">
    Set or update payment terms and due date for the invoice
  </ParamField>

  <ParamField path="notes" type="string">
    Add or edit invoice notes, payment instructions, or terms and conditions
  </ParamField>

  <ParamField path="discount" type="object">
    Apply, modify, or remove percentage or fixed amount discounts. Specify either a percentage (e.g., 10%) or a fixed dollar amount (e.g., \$50).
  </ParamField>

  <ParamField path="status" type="string">
    Update invoice status (only for existing invoices): Draft, Sent, Paid, Overdue, Partially Paid, or Void
  </ParamField>
</Accordion>

<Warning>
  When creating or updating invoices, ensure you have reviewed the customer information and line item details to ensure accuracy. Incorrect amounts or payment terms can lead to payment delays and customer confusion.
</Warning>

## Common Workflows

### Sending a Quote

Quotes help business owners quickly provide pricing estimates to prospective or existing customers before work begins:

1. **Gather** information about the customer and proposed services or products
2. **Create** a draft invoice using `save_invoice` with customer, line items, and pricing
3. **Share** the quote with the customer for review and approval

This workflow enables business owners to respond quickly to quote requests and formalize pricing discussions.

<Tip>
  Quotes are particularly useful for service-based businesses responding to RFPs or providing estimates for project work. Business owners can create multiple quote versions with different pricing scenarios before finalizing.
</Tip>

### Creating Invoices for Completed Work

One of the most common workflows is creating invoices for services rendered or products delivered:

1. **Gather** information about the customer, services provided, and pricing
2. **Create** the invoice using `save_invoice` with customer, line items, date, and due date
3. **Review** the invoice details using `get_invoice` to confirm accuracy before sending

This workflow helps business owners quickly bill clients for completed work while ensuring all details are correct.

### Setting Up Payment Plans

For larger invoices, offering payment plans can improve customer relationships and payment success:

1. **Get** the invoice details to understand the total amount
2. **Update** with installment information using `save_invoice`, specifying installment amounts and dates
3. **Add notes** documenting the payment schedule agreement

Payment plans are common for professional services, large projects, or ongoing retainers where clients prefer to spread payments over time.

## Examples

### "Send a quote to Ruth Smith for \$12k bathroom remodeling. Include a 3k down payment."

**AI uses:** `save_invoice` with:

* `customer`: "Ruth Smith"
* `lineItems`:
  * description: "Bathroom Remodeling", quantity: 1, rate: 12000, amount: 12000
* `installments`:
  * amount: 3000, date: "2025-02-01" (down payment)
  * amount: 9000, date: "2025-03-15" (final payment)
* `date`: today's date
* `notes`: "Quote valid for 30 days. \$3,000 down payment required to begin work."

**AI responds:** "I've created a quote (QUO-1252) for Ruth Smith for bathroom remodeling:

**Total Amount:** \$12,000.00

**Payment Terms:**

* Down payment: \$3,000.00 due February 1, 2025
* Final payment: \$9,000.00 due March 15, 2025

The quote is currently in Draft status. Once Ruth approves, I can update the status to Sent and you can begin work."

***

### "Draft invoice to Joe's Photography for the 1/15 expense with a 20 percent markup and \$1,000 in labor."

**AI uses:** `save_invoice` with:

* `customer`: "Joe's Photography"
* `lineItems`:
  * description: "Materials (expense from 1/15)" with the `expenseId` from Bank Transactions
  * description: "Labor", quantity: 1, rate: 1000, amount: 1000
* `date`: today's date

**AI responds:** "I've created draft invoice INV-1253 for Joe's Photography:

**Line Items:**

1. Materials (expense from 1/15): \$180.00 (marked up 20% from \$150.00)
2. Labor: \$1,000.00

**Total:** \$1,180.00

The invoice is in Draft status. Would you like to set a due date or add any notes before sending?"

***

### "Add a 10 percent discount to that invoice"

**AI uses:** `save_invoice` with:

* Invoice ID from context (INV-1253)
* `discount`: percentage: 10

**AI responds:** "I've added a 10% discount to INV-1253. Here's the updated summary:

**Subtotal:** \$1,180.00
**Discount (10%):** -\$118.00
**New Total:** \$1,062.00

Would you like me to add a note explaining the discount?"

***

### "Show me all overdue invoices"

**AI uses:** `query_invoices` with:

* `status`: "Overdue"

**AI responds:** "You have 3 overdue invoices totaling \$6,250.00:

1. **INV-1247** - ABC Corp - \$3,200.00 - Due January 5th (6 days overdue)
2. **INV-1239** - XYZ Industries - \$2,100.00 - Due December 28th (14 days overdue)
3. **INV-1235** - Smith Consulting - \$950.00 - Due December 15th (27 days overdue)

Would you like me to help you draft follow-up messages for any of these?"

***

### "Create an invoice for Ruth Smith for \$12,000 split into 3 monthly payments"

**AI uses:** `save_invoice` with:

* `customer`: "Ruth Smith"
* `lineItems`: (gathered from context or user clarification)
* `installments`:
  * amount: 4000, date: "2025-02-01"
  * amount: 4000, date: "2025-03-01"
  * amount: 4000, date: "2025-04-01"
* `date`: today's date
* `notes`: "Payment plan: 3 equal installments of \$4,000.00 due on the 1st of each month"

**AI responds:** "I've created INV-1254 for Ruth Smith with a \$12,000.00 payment plan:

**Payment Schedule:**

* Payment 1: \$4,000.00 due February 1, 2025
* Payment 2: \$4,000.00 due March 1, 2025
* Payment 3: \$4,000.00 due April 1, 2025

The invoice notes include the payment plan terms. What line items should I add to the invoice for the \$12,000.00 total?"