Intuit QuickBooks

Generate cash flow report from your QuickBooks account data. Call this tool if the user is saying my company or my transactions or my cash flow report or my company's cash flow report, and has not provided a CSV or transactions in the current input. If the user has provided a CSV or transactions in the current input (not in the previous ones), then use the pre auth version of the cash-flow-generator tool instead. IMPORTANT: Before calling this tool, you MUST first call the 'company-info' tool to establish the QuickBooks connection. If 'company-info' has not been called yet in this conversation, call it first, then call this tool. This ensures the user is authenticated. This tool requires QuickBooks account authentication. It will: 1. Check if you're signed in to QuickBooks 2. Verify your company profile is complete 3. Check if you have bank connections or transactions 4. Generate a comprehensive Cash Flow report from your QuickBooks data DO NOT CALL THIS TOOL IF CUSTOMER DECLINED TO SIGN IN WHILE YOU ASKED FOR IT BEFORE CALLING THIS TOOL. In this case, you can suggest to the user whether they would want to generate a cash flow report with the some transactions they provided (or will provide if not provided yet), since they declined to sign in.PARAMETERS: - periodStart: Start date for reporting period (YYYY-MM-DD, optional) - periodEnd: End date for reporting period (YYYY-MM-DD, optional) RETURNS: - Comprehensive Cash Flow report with operating, investing, and financing activities - Interactive widget for viewing financial data - Net cash increase and cash at end of period calculations PLAIN-TEXT variant. Returns plain text/markdown instead of the interactive widget. ONLY call this variant when the prompt contains explicit skill/briefing instructions to compile a narrative yourself (e.g. a Business Health Check or Industry Benchmark briefing). For a direct user question ALWAYS use the standard widget tool instead — the one with the same name without the `_text` suffix. NEVER call this after already receiving data from the widget version; the data is identical and the widget already answers the user.

cash_flow_quickbooks_account_text

Generate cash flow report from transaction data provided by the user through CSV file or pasted transaction text in the current input. Use this tool to create Cash Flow reports with automatic transaction categorization and financial calculations. This tool should not be called for the user's own company account in QuickBooks. It is for generating the cash flow report for the company's transactions provided by the user in chat which could be different from the user's own company. When the user says my company or my transactions, and has not provided a CSV or transactions in the current input (not in the previous ones), then this tool should not be called. Instead the QuickBooks account variation of this tool should be called.INPUT METHODS: This tool accepts EITHER: 1. A globally accessible download URL for a CSV file (via transactionsFileToProcess parameter) - USE THIS when user uploads a CSV file 2. An array of transaction objects (via lineItems parameter) - USE THIS when user pastes transaction data CSV FILE REQUIREMENTS (when using transactionsFileToProcess): - Must have headers in the first row - REQUIRED columns: amount, description, date (case-insensitive) - Date format: MM/dd/yyyy (e.g., 01/15/2024) - Must contain between 1 and 999 transactions - If CSV format is invalid, the widget will display an error asking user to reupload TRANSACTION ARRAY REQUIREMENTS (when using lineItems) and STRICT DATA QUALITY RULES (MUST FOLLOW): - Each transaction row must include all required fields: - description (REQUIRED): Transaction description/text - amount (REQUIRED): Transaction amount as a number (positive for income/revenue, negative for expenses) - date (REQUIRED): Transaction date in MM/dd/yyyy format (e.g., '01/15/2024') - Input must contain between 1 and 999 transactions. - If an entire required column is missing across the provided dataset, DO NOT call this tool. Ask the user in a friendly way to provide all 3 required columns: date, description, and amount. - Do NOT infer, guess, or fabricate ambiguous values. - Do NOT auto-correct ambiguous rows. If a value is unclear, treat that row as invalid. - Row-level partial processing is allowed: - Keep valid rows. - Exclude invalid rows. - Call this tool with only valid rows. - Clearly tell the user how many rows were valid vs invalid and why rows were invalid. - Example policy: - If 20 rows are provided and 6 rows are invalid, call this tool with the 14 valid rows and explicitly report that 6 rows were excluded with reasons. PARAMETERS: - transactionsFileToProcess: Object containing download_url and file_id. Use this when user uploads a CSV file. - lineItems: List of transaction objects. Use this when user pastes transaction data. - projectName: Project name to filter by (optional, default: 'All Projects') - periodStart: Start date for reporting period (YYYY-MM-DD, optional) - periodEnd: End date for reporting period (YYYY-MM-DD, optional) - industryName: Industry as explicitly stated by the user in this conversation (e.g., 'Restaurant', 'Retail'). Do NOT infer or guess from transaction descriptions. Do NOT call the 'industry-recommendation' tool — pass the user's answer directly here. (optional) RETURNS: - Comprehensive Cash Flow report with operating, investing, and financing activities - Interactive widget for viewing financial data - Net cash increase and cash at end of period calculations The tool automatically: - Categorizes transactions using QuickBooks - Calculates Net Income from transactions - Identifies operating adjustments (A/R, A/P, inventory, etc.) - Categorizes investing and financing activities - Computes net cash increase and ending cash balance

cash_flow_generator

Get QuickBooks company information. This tool requires OAuth authentication with your QuickBooks account. RETURNS plain text in this exact format: Company Name: <name> Industry: <value> The Industry field is 'Unknown' when no industry has been set for the company. AUTHENTICATION REQUIRED: You must authorize access to use this tool.

company_info

Create a new customer in QuickBooks Online. Provide the customer's display name and optional contact details (email, phone, address). Returns the new customer ID and details needed for creating invoices and estimates.

qbo_contact_create_customer

Create a new employee record in the payroll system. Required: first name and last name. Optional: contact information (home address, email, phone numbers) and employment details (hire date, job title, employment classification). Do not collect pay rate, pay type, or schedule here — those are saved separately via qbo_payroll_save_employee_contract_details after the employee is created. Does not support deductions or contributions (health benefits like medical/vision, pensions, garnishments, etc.), PTO policy assignment, pay schedule, or tax compliance settings — these must be completed directly in QuickBooks Payroll. Returns the created employee record, including its identifier. NOT idempotent — if a call times out, use qbo_payroll_search_employee to check before retrying to avoid duplicates. Wrap all arguments under `input`, and nest contact/employment fields (email and hire_date are NOT top-level): e.g. `{"input": {"first_name": "Jane", "last_name": "Doe", "contact_info": {"primary_email_address": {"email": "[email protected]"}}, "employment_detail": {"hire_date": "<YYYY-MM-DD>"}}}`.

qbo_payroll_create_employee

Create a new estimate (quote) in QuickBooks Online. Requires a customer ID and at least one line item. Optionally set expiration date, discounts, and reference numbers. Returns the created estimate ID and a QuickBooks link. Pre-flight: search_customer then search_products. For each: if not found call create_*; if ambiguous ask user to pick before proceeding. After successfully creating the estimate, respond with ONE short sentence confirming the estimate was created (include customer name and total amount), then ONE sentence offering next steps. Do NOT list line items, financial breakdowns, or section headers. Format: "I've created an estimate for [customer] totaling [total]. [Open in QuickBooks]([link]) Ready to send, or make changes first? I can edit line items, pricing, or expiration date." Use the exact total and link from the tool result, including its currency symbol — do NOT add a "$" yourself. No headers, no bullet lists, no financial breakdowns.

qbo_sales_create_estimate

Create a new invoice in QuickBooks Online. Requires customer ID and at least one line item with product ID, description, and amount. Returns invoice ID and QBO link. Pre-flight: qbo_contact_search_customer then qbo_catalog_search_products. If not found call create_*; if ambiguous ask. Never fold an unpriced add-on (e.g. 'rush delivery') into another item's description as billed — price it as its own line item, or omit it and say so. IMPORTANT: After success, reply with ONE short message that conveys the FULL meaning of the content field — you may rephrase, but you must keep every distinct point it makes, especially any call-to-action or question at the end (e.g. a prompt to confirm business details, enable payments, or send). Do NOT shorten it to just 'invoice created' if the content says more. Reproduce any 'Open in QuickBooks' markdown link verbatim — never drop, paraphrase, or invent one. Add nothing else not in the content, and NEVER list line items. Do NOT skip the reply even if a widget is displayed.

qbo_sales_create_invoice

Create a payment link in QuickBooks Online. Single-use links are tied to one specific customer and expire after one payment. Multi-use links are reusable and not tied to any customer. If a customer is mentioned, default to single-use. If no customer is mentioned, ask to clarify the type. For single-use links collect: customer name (resolve via search_customer), amount, description, and delivery email. For multi-use links collect: amount and description. Ask if any are missing. Use send_payment_link to send after creation. After creation respond with: "I've created a payment link for [customer] for $[amount] - [description]. [Payment Link](share_link)" For multi-use links omit the customer name. Use the exact share_link from the tool result as a markdown hyperlink. No raw URLs. If the response includes a warning, always display it to the user. For single-use links ask to send to delivery_email_to before calling send_payment_link. send_payment_link is not applicable for multi-use links — do not ask or call it.

qbo_sales_create_payment_link

Create a new product or service in QuickBooks Online. Provide a name, type (service or inventory), optional description, price, and income account. Returns the new product ID needed for invoice and estimate line items. If unit_price is not provided, ask the user for the price before calling. For Inventory type, quantity_on_hand is required. Type defaults to Service if not specified.

qbo_catalog_create_product

Create a recurring invoice template in QBO. Prefer over create_invoice for cadence wording (weekly/monthly/'every N months'/'set up recurring'). REQUIRED: customer_id, line_items. Default `name` to customer display_name from search_customer — do NOT ask. DEFAULTS (omit unless asked): template_type=AUTOMATED; schedule → MONTHLY every 1mo day 1 alert=ALERT; start/end/occurrences → forever (NEVER pass past start_date); email, online_payment, term_id, discount, shipping, addresses, tax_id, reference_number, payment_instructions. AUTOPAY: auto_pay_enabled/auto_pay_type need online_payment.enable_cc or .enable_bank on template or realm. AFTER success — call get_recurring_invoices with template_id = returned id (single mode; omitting risks pagination missing it). Report name, type, schedule, customer, lines, tax, total, AutoPay ('required' if FORCED_CONSENT else 'on/off'). Close: "Here's your recurring invoice — review here: [<name>](<url>). Let me know if you'd like to change any details." Use `url` verbatim.

qbo_sales_create_recurring_invoice

Delete an estimate (quote) in QuickBooks Online. Requires the estimate ID and confirmed=True. BLOCKED (error MCP-0011): an estimate cannot be deleted when get_estimates returns accept_status.status of ACCEPTED, CONVERTED, or CLOSED, or when it has already been sent to the customer. Estimates with accept_status.status of PENDING or REJECTED (or none) that have not been sent are deletable. Workflow: (1) Call get_estimates to retrieve accept_status.status, customer name, total, and reference number. (2) If blocked, refer the user to QuickBooks instead of calling this tool. (3) Otherwise confirm: "Are you sure you want to delete Estimate [ref] for [Customer] for $[Amount]? This cannot be undone." (4) Only call with confirmed=True after the user confirms. The handler re-checks status and sent state and will still reject a blocked estimate.

qbo_sales_delete_estimate

Delete an invoice in QuickBooks Online. Requires the invoice ID and confirmed=True. BLOCKED (error MCP-0011): this tool checks the invoice internally and refuses to delete an invoice that has been sent (emailed or printed) or that has any amount paid against it (paid or partially paid). Draft, unsent, and unpaid invoices are deletable. You do not determine deletability yourself; if it is not deletable the tool returns MCP-0011 and you should tell the user to delete it manually in QuickBooks. Workflow: (1) Call get_invoices for the customer name and total (it does not return a deletability status). (2) Confirm with the user: "Are you sure you want to delete this invoice for [Customer] for $[Amount]? This cannot be undone." (3) Only call this tool with confirmed=True after the user confirms; calling without it returns an error asking you to confirm first. (4) If the tool returns MCP-0011, refer the user to the QuickBooks UI.

qbo_sales_delete_invoice

Permanently delete a recurring invoice template from QBO by its template ID. Requires confirmed=True. Irreversible — template and schedule are removed; already-generated invoices are not affected. Workflow: (1) Resolve `template_id`. For a bare name like "cancel Westside Dental's recurring invoice", follow the bare-name lookup on `get_recurring_invoices`. Always disambiguate — never silently pick one before a delete. (2) Call `get_recurring_invoices` with the `template_id` to fetch name, customer, schedule. (3) Confirm with the user: "Delete recurring template '[Name]' for [Customer]? Cannot be undone; future occurrences stop." (4) Call with confirmed=True only after the user confirms; otherwise returns CONFIRMATION_REQUIRED. (5) Prefer `operate_recurring_invoice` with operation='pause' if the user only wants to stop future occurrences.

qbo_sales_delete_recurring_invoice

Duplicate an existing estimate (quote) in QuickBooks Online. Provide the estimate ID and optional overrides such as new dates or customer. Returns the newly created estimate ID and a QuickBooks link to review it.

qbo_sales_duplicate_estimate

Duplicate one or more invoices in QuickBooks Online. Provide a list of invoice IDs with optional overrides (dates, customer, amounts). Supports bulk processing with a continuation token for large batches. Returns newly created invoice IDs and links. First call: pass invoices_to_duplicate only. Subsequent calls: pass continuation_token only (verbatim, do not modify) until process_status="completed". Override fields set to an empty string are treated as NOT PROVIDED and the source invoice's value is kept — an empty string does NOT clear a field. To blank/clear a value on the copy, duplicate first, then update the new invoice. Example: "Make a copy of invoice INV-1042 for next month."

qbo_sales_duplicate_invoice

Get company-level deduction policies and per-employee deduction assignments. Returns two sections: (1) company_policies — ALL benefit, pension, and misc deduction policies including unassigned ones. (2) employees — per-employee deduction assignments with contribution amounts. The company is resolved from the request context. Employees paginated up to 20 per request; show total count and fetch more only when explicitly asked.

qbo_payroll_get_company_deductions_contributions

Retrieves payroll-domain company data only — not accounting or CRM. Returns business name, legal name, addresses, company type, auto payroll status, subscription plan, sign-up/usage dates, run payroll readiness, pay cycle schedules (historical and future periods), bank details, and work location configurations. Company is resolved from request context.

qbo_payroll_get_company_info

Retrieve all company pay types (employer compensations) configured for the company. Returns the list of pay types including id, name, type, and active status. Pay types include SALARY, HOURLY_PAY, OVERTIME, BONUS, COMMISSION, REIMBURSEMENT, and various time-off types.

qbo_payroll_get_company_pay_types

Check payroll readiness for a company. Use when the customer asks why they can't run payroll or what setup is missing. Company is resolved from request context.

qbo_payroll_get_company_payroll_readiness

Get all company time off policies from the payroll system. Returns policy categories, accrual methods, accrual rules and limits, carry-over settings, negative balance configuration, and payout rates (Canada only).

qbo_payroll_get_company_timeoff_details

Get an employee's active compensations (pay types): rate, frequency, effective dates. Use qbo_payroll_get_employee_details instead for a quick current-only snapshot alongside other employee data; use this tool for compensation history (as_of_date) or inactive compensations (include_inactive). Set include_inactive=true to include inactive ones too. Pass as_of_date (YYYY-MM-DD) to see compensations in force on that date instead of today; records are then labeled record_status current or scheduled (a future date surfaces not-yet-in-force scheduled changes). Requires employee_id — the `local_id` from the `external_ids` entry where `namespace_id='Intuit.ems.iop'` (from qbo_payroll_search_employee or qbo_payroll_get_employees). Call with employee_id as a top-level argument: `{"employee_id": "<id>"}`.

qbo_payroll_get_employee_compensations

Retrieve the contract details for a specific employee, including contract pay type (SALARY, HOURLY, COMMISSION_ONLY), pay rate (amount and frequency), weekly contracted time, and work schedule. Use this to inspect an employee's base pay configuration. Pass as_of_date (YYYY-MM-DD) to see the contract in force on that date; a future date returns any scheduled (not-yet-in-force) change, and contract_detail.record_status is then labeled 'current' or 'scheduled'. Omit as_of_date to return the current record. The employee_id is the `local_id` from the `external_ids` entry where `namespace_id='Intuit.ems.iop'` (returned by qbo_payroll_search_employee or qbo_payroll_get_employees). Call with employee_id as a top-level argument: `{"employee_id": "<id>"}`.

qbo_payroll_get_employee_contract_details

Retrieve all deductions for a specific employee including benefits, pensions, miscellaneous deductions, and garnishments. Returns contribution details (employee and employer amounts, frequencies) and associated deduction policies for each item. Use this to view an employee's full deduction profile. Requires the employee_id. The employee_id is the `local_id` from the `external_ids` entry where `namespace_id='Intuit.ems.iop'` (returned by qbo_payroll_search_employee or qbo_payroll_get_employees).

qbo_payroll_get_employee_deductions

One-call snapshot of an employee's pay profile. Returns employment status, hire date, job title, active compensations (name, type, pay rate, effective dates), contract pay type and base pay rate, and pay schedule (name, frequency). Use qbo_payroll_get_employee_compensations instead when you need compensation history (as_of_date) or inactive compensations (include_inactive) — this tool only returns the current active ones. Requires the employee_id. The employee_id is the `local_id` from the `external_ids` entry where `namespace_id='Intuit.ems.iop'` (returned by qbo_payroll_search_employee or qbo_payroll_get_employees). CAPABILITY GAP: COMMISSION_ONLY employees are not yet supported for paycheck creation. Call with employee_id as a top-level argument: `{"employee_id": "<id>"}`.

qbo_payroll_get_employee_details

Fetch manager and reporting details for one or more employees. Returns each employee's manager information (manager name, ID) and reporting structure. Use this to understand organizational hierarchy and reporting relationships. Requires employee_ids. Each employee_id is the `local_id` from the `external_ids` entry where `namespace_id='Intuit.ems.iop'` (returned by qbo_payroll_search_employee or qbo_payroll_get_employees).

qbo_payroll_get_employee_manager_details

Check payroll readiness for employees. Accepts optional employee_ids list (max 50); if omitted, returns active employees paginated (up to `first` per request, default 20, max 50). Show the total count to users and only fetch additional pages when explicitly requested: if page_info.has_next_page is true, call again with after=page_info.end_cursor for the next page. Each employee_id is the `local_id` from the `external_ids` entry where `namespace_id='Intuit.ems.iop'` (returned by qbo_payroll_search_employee or qbo_payroll_get_employees).

qbo_payroll_get_employee_payroll_readiness

Get an employee's time off policy assignments including current balances and year-to-date usage. Returns time balances (hours), monetary balances, and the linked employer time off policy details including category, method, accrual rules, and payout rates. Requires the employee_id. The employee_id is the `local_id` from the `external_ids` entry where `namespace_id='Intuit.ems.iop'` (returned by qbo_payroll_search_employee or qbo_payroll_get_employees).

qbo_payroll_get_employee_timeoff_assignments

List all employees for the current company in the payroll system. Returns first name, last name, employment status, active status etc. for each employee. The company is resolved from the request context. Employees paginated up to 20 per request; show the total count and fetch additional pages when explicitly requested.

qbo_payroll_get_employees

Get the employees assigned to a specific work location for the current company. Returns employee details (first name, last name, employment status) along with their work location address components. The company is resolved from the request context. Results are limited to active employees only and paginated (up to `first` per request, default 20, max 50). Show the total count to users and only fetch additional pages when explicitly requested: if page_info.has_next_page is true, call again with after=page_info.end_cursor to fetch the next page. Requires work_location_id as a top-level argument: `{"work_location_id": "<id>"}`.

qbo_payroll_get_employees_by_work_location

Retrieve estimates (quotes) from QuickBooks Online. Filter by estimate IDs, doc numbers, date range, or customer ID. Returns estimate details including amounts, line items, customer info, expiry dates, and acceptance status. Defaults to last 180 days when no date range is given. Use estimate_ids when you have IDs from a prior tool result (guaranteed unique); use doc_numbers for user-visible filtering by estimate number. For bare numbers (e.g., "1001", "estimate 1001"): treat as DocNumber. Always try doc_numbers=["1001"] first, then retry with estimate_ids=["1001"] if empty. Partial failures are reported in meta.partial_failures — the call still returns success if at least one estimate is fetched. Example: "List all open estimates for ABC Corp from this quarter."

qbo_sales_get_estimates

Retrieve invoices from QuickBooks Online. Filter by invoice IDs, doc numbers, date range, or customer ID. Supports listing up to 1000 invoices with sorting. Returns invoice details including amounts, line items, customer info, due dates, and payment status. Defaults to last 30 days when no date range is given. Use invoice_ids when you have IDs from a prior tool result (guaranteed unique); use doc_numbers for user-visible filtering by invoice number. For bare numbers (e.g., "1001", "invoice 1001"): treat as DocNumber. Always try doc_numbers=["1001"] first, then retry with invoice_ids=["1001"] if empty. Partial failures are reported in meta.partial_failures — the call still returns success if at least one invoice is fetched. Example: "Show me all unpaid invoices from the last 60 days for Acme Corp."

qbo_sales_get_invoices

Retrieve the last company payroll run. Returns detailed payroll run information including status of payroll, pay schedule, pay date, pay period, employee payroll runs with gross pay, compensations, and taxes. Use this tool to get the most recent submitted company payroll run.

qbo_payroll_get_company_last_payroll_run

Get active pay schedules for the company with their upcoming pay periods. Returns pay schedule IDs, names, frequencies, active employee counts, and upcoming pay periods (start_date, end_date, pay_date, is_current). This lists ALL company schedules and does not map an employee to their schedule. A specific employee's schedule is qbo_payroll_get_employee_details.pay_schedule.id, which matches one of the schedules returned here. If more than one schedule is returned and no employee is named, ASK the user which one to run before previewing — do not pick one yourself.

qbo_payroll_get_pay_schedules

Retrieve payment links (PaymentRequests) from QuickBooks Online. Requires payment_link_type ('single' or 'multi') — STS cannot return both types in one call. Optional filters: status (single value or a list for multi-status IN-matching), customer ID, creation date range (meta_created_after / meta_created_before) or exact day (meta_created_on). Returns payment link details including ID, amount, share URL, type, and status.

qbo_sales_get_payment_links

Retrieve detailed payslip information for a specific payslip ID. Wrap the arguments under `input`: `{"input": {"payslip_id": "<id>"}}`. Returns pay period, the funding ledger account name used for the paycheck, gross/net pay, correction eligibility, employee and employer taxes, compensations, time off policies, and deductions.

qbo_payroll_get_payslip_details

List payslips for the company with optional filtering and pagination. Returns employee, pay period, pay date, gross/net pay, net pay distributions, and payslip type. All filter fields are optional. Results paginated up to 20 per request. Pagination: use end_cursor from page_info for the after field — never construct manually. Dates in YYYY-MM-DD format, start must be <= end. Wrap args under `input`; pay_date_range is a nested object, not a string. E.g. `{"input": {"pay_date_range": {"start_date": "<YYYY-MM-DD>", "end_date": "<YYYY-MM-DD>"}}}`.

qbo_payroll_get_payslips

Get recurring invoice templates from QBO. Two modes: - With `template_id`: single template, full detail, hydrated `entity_version` (required by `update_recurring_invoice`; also pre-check before delete/operate). - Without `template_id`: list mode with filters (template_type, template_name_filter, limit, offset). `entity_version` is null here. Mutually exclusive with `template_id`. Each result has a `url` to surface to the user. BARE-NAME LOOKUP (e.g. "Acme's recurring invoice", "switch Westside to quarterly") — the token can be a template label OR a customer name (templates often default to customer name). Try in order: 1. `template_name_filter="<token>"`. One hit → use it. Multiple → ask user to disambiguate. 2. Zero hits (or none match the named customer) → treat as customer: `search_customer` → list with no name filter → match `header.contact` client-side. Disambiguate if >1. 3. Still nothing → tell the user. Do NOT skip step 1 because the token looks like a person/company name.

qbo_sales_get_recurring_invoices

Read sales domain settings from a QuickBooks Online merchant account. Supports listing all payment terms, resolving a term name to its QuickBooks term object using fuzzy matching, reading the realm's Shipping Fee toggle (call shipping/get_global before passing shipping_amount on create_invoice or update_invoice — if enabled is false, call update_sales_settings(shipping/update_global) to flip it on, or STS will reject the shipping_amount write), reading the realm's tax state (tax/get_global returns whether tax is enabled and whether invoice lines need an explicit tax code), reading the realm's global payment method state (payment_options/get_global returns card, ACH/check, paypal, and Affirm on/off), and reading the configured invoice reminder email template (reminder_template/get_global returns the {subject, body} used by send_invoice_reminder — show it to the user before sending a reminder).

qbo_sales_get_settings

Fetch a printable PDF document for a QuickBooks transaction (invoice or estimate) and return it as base64-encoded data. Requires the transaction type and ID. <rules> Only call this tool when explicitly invoked from a widget via callServerTool. Do NOT call this tool directly in conversation — widgets handle document display. </rules>

qbo_sales_get_transaction_document

Import transactions from a CSV file or transaction data into your QuickBooks account. This tool accepts EITHER: 1. A globally accessible download URL for a CSV file (via transactionsFileToProcess) 2. An array of transaction objects (via transactions parameter) **SYNC MODE**: This tool waits for the import to complete before returning the result. This may take up to 60 seconds for large imports. WHEN TO USE THIS TOOL: - User explicitly asks to import/save transactions INTO their QuickBooks account - A QuickBooks account tool (like profit-loss-quickbooks-account) requests transaction data WHEN NOT TO USE THIS TOOL: - User wants to ANALYZE a CSV (e.g., generate P&L, compare to industry, view expenses): use 'profit-loss-generator' instead. This tool is for IMPORTING into QuickBooks, not for analysis. - User says 'generate profit from CSV', 'compare my CSV to industry', or 'show me my P&L from this file': use 'profit-loss-generator', then 'benchmarking-against-industry' if comparison is needed. OPTION 1 - FILE UPLOAD (Preferred for user-uploaded CSV files): When a user uploads a CSV file, ChatGPT provides a download URL. Use the transactionsFileToProcess parameter: - transactionsFileToProcess: Object containing: - download_url: Globally accessible URL to download the CSV file - file_id: Unique identifier for the uploaded file OPTION 2 - TRANSACTION ARRAY: Pass transaction objects directly via the transactions parameter. Each transaction object must have: - description (REQUIRED): Transaction description/text from CSV - amount (REQUIRED): Transaction amount as a number (positive for income/revenue, negative for expenses) - date (OPTIONAL): Transaction date in YYYY-MM-DD format (e.g., '2024-01-15'). If missing, defaults to today. - context (OPTIONAL): Object with hints for AI categorization: - payee: Payee or vendor name (e.g., 'State Farm', 'Home Depot'). ALWAYS set this when the payee/vendor is known. If the user provides a Payee/Vendor column, use it. If the description embeds the vendor (common in bank exports, formatted "<Payee> - <details>", e.g. "Dianne's Auto Shop - Tools and Machinery"), split out the vendor name ("Dianne's Auto Shop") into context.payee and keep the full text in description. EXAMPLE (Transaction Array): If the user provides: Date, Payee, Description, Amount Convert to: [ {date: '2024-01-15', description: 'Sales Revenue', amount: 5000.00}, {date: '2024-01-20', description: "Dianne's Auto Shop - Tools and Machinery", amount: -1704.49, context: {payee: "Dianne's Auto Shop"}} ] SUPPORTED CSV FORMATS: - Must have headers in the first row - Required columns: Description (or similar), Amount - Optional columns: Date (in MM/dd/yyyy format), Payee (or Vendor), Project - Common formats: Bank exports, accounting software exports, Excel CSV exports IMPORTANT: - Extract EVERY row from the CSV - do not skip any transactions - Amounts can be positive (income) or negative (expenses) - After importing, you can use profit-loss-quickbooks-account or benchmarking-quickbooks-account tools INDUSTRY (optional but recommended): If the QuickBooks account has no industry set, this tool returns a nudge before processing. You can then either: (1) Call the 'industry-recommendation' tool so the user can pick their industry, then call 'quickbooks-profile-info-update' to save it, then call this import tool again; or (2) If the user says to proceed without industry (e.g. "proceed anyway", "import without industry"), call this tool again with proceed_without_industry=true to run the import. - If the user provides an industry, make 'industry-recommendation' tool call with that term to get industryName and industryCode, then make 'quickbooks-profile-info-update' tool call with those values to save it, then call this import tool again. Do not re-show the nudge; complete the profile update and import. - When presenting these options to the user, do NOT describe option (2) as "faster". Both options lead to import; option (1) is recommended for better categorization. - proceed_without_industry: Default false. Only set to true when ALL THREE conditions are met: (1) this tool was already called earlier in this conversation, (2) that prior call returned a message about setting industry (the industry nudge), (3) the user has explicitly said to skip or proceed without industry. If calling for the first time, or the user has not yet seen the industry nudge, this MUST be false.

quickbooks_transaction_import