Invoices

The Invoice API provides comprehensive endpoints for managing invoices, including CRUD operations, payment tracking, scheduling, and analytics.

Query Endpoints

get

Retrieve a paginated list of invoices for the current team.

status

string

Filter by status: “draft”, “unpaid”, “paid”, “overdue”, “canceled”, “scheduled”

customerId

string

Filter by customer ID

string

Search query for invoice number or customer name

start

string

Start date for filtering (ISO 8601)

end

string

End date for filtering (ISO 8601)

sort

array

Array of sort objects with field and direction

import { trpc } from '@/lib/trpc';

const invoices = await trpc.invoice.get.query({
  status: 'unpaid',
  start: '2024-01-01',
  end: '2024-12-31',
});

getById

Retrieve a specific invoice by ID.

string

required

The invoice ID (UUID)

invoice

object

Show Invoice properties

string

Invoice UUID

invoiceNumber

string

Human-readable invoice number

status

string

Invoice status

amount

number

Total amount

currency

string

Three-letter currency code

issueDate

string

ISO 8601 timestamp

dueDate

string

ISO 8601 timestamp

lineItems

array

Array of line item objects

customer

object

Customer object if customerId is set

const invoice = await trpc.invoice.getById.query({
  id: 'uuid-here',
});

getInvoiceByToken

Public endpoint - no authentication required

Retrieve an invoice using a secure token (used for customer portal).

token

string

required

The URL-encoded secure token

const invoice = await trpc.invoice.getInvoiceByToken.query({
  token: encodedToken,
});

paymentStatus

Get payment status summary for the team’s invoices.

data

object

Show properties

paid

number

Total amount paid

unpaid

number

Total amount unpaid

overdue

number

Total amount overdue

searchInvoiceNumber

Search for invoice numbers (autocomplete).

query

string

required

Search query

results

array

Array of matching invoice numbers

invoiceSummary

Get invoice statistics and summary.

statuses

array

Array of statuses to filter by

data

object

Show properties

totalCount

number

Total number of invoices

totalAmount

number

Total amount across all invoices

currency

string

Base currency

byStatus

object

Breakdown by status

defaultSettings

Get default settings for creating a new invoice.

data

object

Show properties

string

Pre-generated UUID for new invoice

invoiceNumber

string

Next available invoice number

currency

string

Default currency from team settings

template

object

Template settings (labels, formatting, etc.)

issueDate

string

Today’s date (ISO 8601)

dueDate

string

Due date based on payment terms (ISO 8601)

const defaults = await trpc.invoice.defaultSettings.query();

// Use defaults to populate new invoice form
setFormData(defaults);

Mutation Endpoints

draft

Create a new draft invoice.

string

required

UUID for the invoice (use defaultSettings to get one)

invoiceNumber

string

Invoice number (auto-generated if not provided)

customerId

string

Customer UUID

customerName

string

Customer name if no customerId

currency

string

required

Three-letter currency code

lineItems

array

required

Array of line items

issueDate

string

required

Issue date (ISO 8601)

dueDate

string

required

Due date (ISO 8601)

template

object

required

Template configuration

const invoice = await trpc.invoice.draft.mutate({
  id: generatedId,
  customerId: 'customer-uuid',
  currency: 'USD',
  lineItems: [
    {
      name: 'Web Development',
      quantity: 40,
      price: 150,
      vat: 0,
    },
  ],
  issueDate: new Date().toISOString(),
  dueDate: addDays(new Date(), 30).toISOString(),
  template: templateSettings,
});

create

Finalize and create an invoice from a draft.

string

required

The draft invoice ID

deliveryType

string

required

“create” | “create_and_send” | “scheduled”

scheduledAt

string

Required if deliveryType is “scheduled” (ISO 8601)

data

object

The created/scheduled invoice object

// Create immediately
const invoice = await trpc.invoice.create.mutate({
  id: draftId,
  deliveryType: 'create',
});

// Create and send
const invoice = await trpc.invoice.create.mutate({
  id: draftId,
  deliveryType: 'create_and_send',
});

// Schedule for later
const invoice = await trpc.invoice.create.mutate({
  id: draftId,
  deliveryType: 'scheduled',
  scheduledAt: '2024-12-01T09:00:00Z',
});

update

Update an existing invoice.

string

required

The invoice ID

status

string

New status

lineItems

array

Updated line items

dueDate

string

Updated due date

const updated = await trpc.invoice.update.mutate({
  id: invoiceId,
  status: 'paid',
});

delete

Delete an invoice.

string

required

The invoice ID

await trpc.invoice.delete.mutate({
  id: invoiceId,
});

duplicate

Duplicate an existing invoice with a new invoice number.

string

required

The invoice ID to duplicate

data

object

The new invoice object

const duplicated = await trpc.invoice.duplicate.mutate({
  id: invoiceId,
});

remind

Send a payment reminder for an invoice.

string

required

The invoice ID

date

string

required

Timestamp of when reminder was sent (ISO 8601)

await trpc.invoice.remind.mutate({
  id: invoiceId,
  date: new Date().toISOString(),
});

Scheduling

updateSchedule

Update the scheduled send date for a scheduled invoice.

string

required

The scheduled invoice ID

scheduledAt

string

required

New scheduled date (ISO 8601, must be in the future)

await trpc.invoice.updateSchedule.mutate({
  id: invoiceId,
  scheduledAt: '2024-12-15T10:00:00Z',
});

cancelSchedule

Cancel a scheduled invoice and return it to draft status.

string

required

The scheduled invoice ID

await trpc.invoice.cancelSchedule.mutate({
  id: invoiceId,
});

Time Tracking Integration

createFromTracker

Create an invoice from time tracking entries.

projectId

string

required

The tracker project UUID

dateFrom

string

required

Start date for time entries (ISO 8601 date)

dateTo

string

required

End date for time entries (ISO 8601 date)

data

object

The created draft invoice with calculated hours and amount

const invoice = await trpc.invoice.createFromTracker.mutate({
  projectId: 'project-uuid',
  dateFrom: '2024-11-01',
  dateTo: '2024-11-30',
});

// Invoice will have a line item with:
// - name: "Project Name (Nov 1, 2024 - Nov 30, 2024)"
// - quantity: total hours tracked
// - price: project hourly rate

Analytics

mostActiveClient

Get the client with the most invoices.

data

object

Show properties

customerId

string

Customer UUID

customerName

string

Customer name

invoiceCount

number

Number of invoices

inactiveClientsCount

Get the number of clients with no invoices in the last 90 days.

count

number

Number of inactive clients

averageDaysToPayment

Get the average number of days from invoice issue to payment.

days

number

Average days to payment

averageInvoiceSize

Get the average invoice amount.

data

object

Show properties

amount

number

Average amount

currency

string

Currency code

topRevenueClient

Get the client with the highest total revenue.

data

object

Show properties

customerId

string

Customer UUID

customerName

string

Customer name

totalRevenue

number

Total revenue amount

newCustomersCount

Get the number of new customers in the current period.

count

number

Number of new customers

Getting Started

Resources

Query Endpoints

get

getById

getInvoiceByToken

paymentStatus

searchInvoiceNumber

invoiceSummary

defaultSettings

Mutation Endpoints

draft

create

update

delete

duplicate

remind

Scheduling

updateSchedule

cancelSchedule

Time Tracking Integration

createFromTracker

Analytics

mostActiveClient

inactiveClientsCount

averageDaysToPayment

averageInvoiceSize

topRevenueClient

newCustomersCount

Build docs developers (and LLMs) love

Getting Started

Resources

​Query Endpoints

​get

​getById

​getInvoiceByToken

​paymentStatus

​searchInvoiceNumber

​invoiceSummary

​defaultSettings

​Mutation Endpoints

​draft

​create

​update

​delete

​duplicate

​remind

​Scheduling

​updateSchedule

​cancelSchedule

​Time Tracking Integration

​createFromTracker

​Analytics

​mostActiveClient

​inactiveClientsCount

​averageDaysToPayment

​averageInvoiceSize

​topRevenueClient

​newCustomersCount

Build docs developers (and LLMs) love

Query Endpoints

get

getById

getInvoiceByToken

paymentStatus

searchInvoiceNumber

invoiceSummary

defaultSettings

Mutation Endpoints

draft

create

update

delete

duplicate

remind

Scheduling

updateSchedule

cancelSchedule

Time Tracking Integration

createFromTracker

Analytics

mostActiveClient

inactiveClientsCount

averageDaysToPayment

averageInvoiceSize

topRevenueClient

newCustomersCount