Skill: Search Invoices

The Search Invoices skill is a multi-action skill that handles searching for existing invoices, creating new invoices, and updating existing ones in QuickBooks Online. The action parameter determines which operation is performed.

Parameters

Common parameters

Parameter	Type	Required	Description
action	string	Yes	The operation: search, create, or update.

Search parameters

Used when action is search.

Parameter	Type	Required	Description
customer_id	string	No	Filter invoices by QuickBooks customer ID.
doc_number	string	No	Filter by invoice number (exact match).
start_date	string	No	Filter invoices with a transaction date on or after this date (YYYY-MM-DD).
end_date	string	No	Filter invoices with a transaction date on or before this date (YYYY-MM-DD).
due_date_start	string	No	Filter invoices with a due date on or after this date (YYYY-MM-DD).
due_date_end	string	No	Filter invoices with a due date on or before this date (YYYY-MM-DD).
max_results	integer	No	Maximum number of invoices to return. Defaults to 100.

Create parameters

Used when action is create.

Parameter	Type	Required	Description
customer_id	string	Yes	QuickBooks customer ID for the invoice.
line_items	array	Yes	Array of line item objects. Each item includes description, amount, quantity, unit_price, and optionally item_ref (product/service ID).
due_date	string	No	Invoice due date (YYYY-MM-DD).
doc_number	string	No	Custom invoice number. Auto-generated if omitted.
bill_email	string	No	Email address to send the invoice to.
bill_addr	object	No	Billing address with line1, line2, city, country_sub_division_code, postal_code, country.
ship_addr	object	No	Shipping address (same structure as bill_addr).
private_note	string	No	Internal note not visible to the customer.
customer_memo	string	No	Note visible to the customer on the invoice.

Update parameters

Used when action is update.

Parameter	Type	Required	Description
id	string	Yes	QuickBooks invoice ID.
sync_token	string	Yes	Current sync token for optimistic concurrency.
line_items	array	No	Updated line items (replaces all existing line items).
due_date	string	No	Updated due date.
bill_email	string	No	Updated billing email.
bill_addr	object	No	Updated billing address.
ship_addr	object	No	Updated shipping address.
private_note	string	No	Updated internal note.
customer_memo	string	No	Updated customer-facing note.

Caution

When updating an invoice, the line_items array replaces all existing line items. If you want to add a line item, you must include all existing line items plus the new one. The agent typically handles this by first searching for the invoice to get current line items.

Example usage

Search

“Show me all invoices for Acme Corp from this quarter.”

The agent first looks up Acme Corp’s customer ID, then invokes:

• action: search
• customer_id: 12345
• start_date: 2026-01-01
• end_date: 2026-03-31

Create

“Create an invoice for Acme Corp: 10 hours of consulting at $150/hour, due in 30 days.”

The agent invokes:

• action: create
• customer_id: 12345
• line_items: [{ "description": "Consulting Services", "quantity": 10, "unit_price": 150 }]
• due_date: 2026-04-17

Update

“Change the due date on invoice #1042 to April 30.”

The agent first searches for the invoice to get its id and sync_token, then invokes:

• action: update
• id: 789
• sync_token: 3
• due_date: 2026-04-30

Response structure

• Search returns an array of invoice records with all fields (id, doc_number, customer, line items, amounts, dates, status, balance).
• Create returns the newly created invoice record with its auto-generated ID.
• Update returns the updated invoice record with the new sync token.

API endpoint

POST /api/quickbooks/v1.0/search-invoices

---

Related skills: Query Customer | Customer Upsert | Get Uncleared Transactions