feat(quickbooks): add observable PO-to-bill linking

[BillLeoutsakosvl346]

What changed

• Extended Create Bill with optional Purchase Order ID and PO line ID pairs on individual Bill lines.
• Added truthful post-create linkage reporting through linkingRequested, linkingSucceeded, linkedLines, missingLinks, and linkingWarning.
• Preserved the native QuickBooks Bill response and standalone Bill behavior.
• Documented native PO/Bill line IDs and linked-transaction fields without adding a new QuickBooks operation.

Why

QuickBooks requires line-level TxnLineId values to establish PO-to-Bill relationships. It may also create the Bill while silently omitting an invalid or unavailable requested link. The tool therefore verifies the returned Bill and reports exactly which requested links QuickBooks established instead of treating HTTP success as proof of linkage.

Validation

• Independent full-integration review against staging: approved with no actionable findings.
• 539 reviewer-run targeted tests; 313 final local QuickBooks/OAuth/serializer/redaction tests.
• Sim TypeScript type-check.
• Tool metadata and generated documentation checks.
• API validation, bare-icon validation, and client-boundary validation.
• Repository format and lint checks.
• git diff --check and memory-load audit.
• Sandbox acceptance for standalone, full, partial, mixed, multi-line, multi-PO, omitted-link, already-linked, and vendor-mismatch cases.

Stack

• Base: feat/quickbooks-04-accounting at 8d443814c4f29f3a8f4acb36fabed7d0df44d182
• Head: feat/quickbooks-04a-po-bill-linking

This PR must not be merged automatically.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 3, 2026 7:49am

[cursor]

PR Summary

Medium Risk
Changes affect payable bill creation and PO linkage semantics in QuickBooks workflows; incorrect handling of partial links could misstate procurement state, though standalone bill behavior is preserved and linkage is reported explicitly.

Overview
Create Bill can now request Purchase Order links by supplying paired purchaseOrderId and purchaseOrderLineId on individual expense lines. The block routes bill creation through parseQuickBooksBillLines instead of the generic purchasing-line parser, and the wand prompt documents the paired PO fields for Create Bill only.

After creation, the action exposes observable linkage results: linkingRequested, linkingSucceeded, linkedLines, missingLinks, and linkingWarning, so workflows can tell whether QuickBooks actually linked each requested PO line (a successful HTTP response does not imply every link was applied).

Docs and integration metadata are updated to describe optional PO-linked bill creation, the new outputs, and expanded native purchasing Line / LinkedTxn field breakdowns across purchasing transaction schemas. Block meta and payables skill content now steer reviewers to read PO line IDs and inspect linkage fields before paying.

^{Reviewed by Cursor Bugbot for commit afdc799. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

The PR extends QuickBooks Create Bill with optional line-level Purchase Order references and reports whether QuickBooks returned each requested link.

• Validates paired Purchase Order and line identifiers while preserving standalone Bill behavior.
• Adds transaction- and line-level QuickBooks linkage fields to the create payload.
• Verifies returned Bill lines and exposes confirmed links, missing links, and a partial-link warning.
• Updates block metadata, generated contracts, documentation, and focused tests.

Confidence Score: 5/5

The PR appears safe to merge, although the user explicitly requested that it not be merged automatically.

No blocking failure remains.

Important Files Changed

Filename	Overview
apps/sim/tools/quickbooks/purchasing_utils.ts	Adds Bill-specific line parsing, PO linkage payload construction, and post-create linkage verification while retaining the shared purchasing-line path.
apps/sim/tools/quickbooks/create_bill.ts	Extends Create Bill response transformation and output metadata with observable linkage results.
apps/sim/tools/quickbooks/types.ts	Defines linked-transaction shapes, Bill-link inputs and outputs, and richer purchasing transaction line metadata.
apps/sim/blocks/blocks/quickbooks.ts	Maps Create Bill through the Bill-specific parser and exposes linkage status fields to workflows.
apps/sim/tools/quickbooks/purchasing.test.ts	Covers standalone, linked, partial, missing, mixed, duplicate, and operation-scoped PO-link behavior.

Sequence Diagram

sequenceDiagram
  participant Workflow
  participant Tool as Create Bill Tool
  participant QBO as QuickBooks
  Workflow->>Tool: Bill lines with optional PO and PO-line IDs
  Tool->>Tool: Validate paired IDs and build LinkedTxn fields
  Tool->>QBO: POST Bill
  QBO-->>Tool: Created native Bill
  Tool->>Tool: Compare requested links with Bill Line[].LinkedTxn
  Tool-->>Workflow: Bill plus linkingSucceeded, linkedLines, missingLinks, warning

Loading

_{Reviews (2): Last reviewed commit: "fix(quickbooks): keep shared line exampl..." | Re-trigger Greptile}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 702149c. Configure here.}

[BillLeoutsakosvl346]

@greptileai