Update Purchase Order with Line Items

Updates an existing purchase order in QuickBooks with line item details. This action allows you to modify purchase orders for vendor procurement, including updating quantities, prices, and line items.

Overview

• Purpose: Update existing purchase orders in QuickBooks with modified line item information.
• Use Cases: Adjusting order quantities, updating pricing, modifying line items, changing vendor details, updating order status, procurement workflow automation.
• API Method: PUT /purchase-orders
• QuickBooks API: Uses QuickBooks Online API /v3/company/\{companyId\}/purchaseorder endpoint.
• Required Scope: com.intuit.quickbooks.accounting

Required Input Fields

Purchase Order ID: Unique identifier for the purchase order to update.

QuickBooks ID: The QuickBooks internal ID must be in the ‘quickbooks-sandbox_id’ custom field.

Purchase Order Number: The PO number for reference and tracking.

Status: Current status of the purchase order (draft, pending, open, closed, cancelled).

Vendor: Vendor information with custom fields.

Purchase Order Line Items: Array of line items with product details, quantities, and pricing.

Purchase Order Status

• Draft: Purchase order is in draft state, not yet submitted.
• Pending: Purchase order is pending approval or processing.
• Open: Purchase order is active and awaiting fulfillment.
• Closed: Purchase order has been completed and closed.
• Cancelled: Purchase order has been cancelled.

Vendor Configuration

• Custom Fields: Object containing vendor metadata and identifiers.
• Vendor Reference: The vendor object should contain custom fields with QuickBooks vendor ID.
• Vendor Lookup: Ensure the vendor exists in QuickBooks before updating the PO.

Line Item Structure

• Line Number: Sequential number identifying the line item position.
• Quantity: Number of units ordered.
• Unit Price: Price per unit for the item.
• Amount: Total line amount (typically quantity × unit price).
• Product: Product information with custom fields containing QuickBooks item ID.
• Custom Fields: Each line item must have ‘quickbooks-sandbox_id’ in custom fields.

Product Configuration

• QuickBooks Item ID: Required field ‘quickbooks-sandbox_id’ containing the item’s internal ID in QuickBooks.
• Custom Fields: Object containing product metadata and identifiers.
• Item Validation: Ensure the item exists and is active in QuickBooks.

Update Process

1. Step 1: Action retrieves the company ID from QuickBooks connection.
2. Step 2: Input purchase order is mapped to QuickBooks purchase order structure.
3. Step 3: Mapped data is sent to QuickBooks API for update.
4. Step 4: Response is mapped back to the standard purchase order format.
5. Step 5: Updated purchase order is returned with current values.

Output

• Purchase Order ID: The ID of the updated purchase order.
• QuickBooks ID: QuickBooks internal ID in custom fields.
• Purchase Order Number: Updated PO number.
• Status: Current status after update.
• Vendor: Updated vendor information.
• Line Items: Array of updated line items with current quantities and pricing.

QuickBooks ID Requirements

[!IMPORTANT] Purchase Order ID: Must match an existing purchase order in QuickBooks.

[!IMPORTANT] Vendor ID: Must be a valid QuickBooks vendor ID in custom fields.

[!IMPORTANT] Item IDs: Each line item must reference a valid QuickBooks item ID.

• ID Format: QuickBooks IDs are numeric strings stored in ‘quickbooks-sandbox_id’ custom field.
• Sync Token: QuickBooks uses sync tokens for optimistic locking - ensure you have the latest version.

Required Permissions

[!IMPORTANT] OAuth Scope: Requires com.intuit.quickbooks.accounting scope for full accounting access.

• Company Access: User must have access to the QuickBooks company.
• User Consent: Users must grant permission during OAuth flow.
• Write Access: Requires write permissions to modify purchase orders.

Error Handling

• Missing Input: Throws error if purchase order object is not provided.
• Invalid PO ID: QuickBooks returns error if purchase order doesn’t exist.
• Invalid Vendor: Error if vendor ID doesn’t exist or is inactive.
• Invalid Items: Error if any item ID doesn’t exist or is inactive.
• Stale Data: Error if sync token doesn’t match (another update occurred).
• Retry Logic: Automatically retries failed requests up to 3 times.

Important Considerations

[!WARNING] Sparse Update: QuickBooks supports sparse updates - only changed fields are updated.

[!IMPORTANT] Sync Token: Always use the latest sync token to avoid conflicts.

• Line Item IDs: Preserve line item IDs when updating to maintain references.
• Status Transitions: Some status changes may be restricted based on QuickBooks settings.
• Vendor Changes: Changing vendors may not be allowed on existing POs.
• Closed POs: Closed purchase orders typically cannot be modified.

Tips

[!TIP] Always sync purchase orders first to get the latest data and sync tokens

[!TIP] Store QuickBooks IDs in the ‘quickbooks-sandbox_id’ custom field for all entities

[!IMPORTANT] Preserve the sync token from the latest sync to avoid update conflicts

[!TIP] Validate that vendor and item IDs exist in QuickBooks before updating

[!TIP] Use the purchase order number for user-friendly reference and tracking

[!WARNING] Check the current status before updating - closed POs may not be modifiable

[!TIP] Preserve line item IDs when updating to maintain QuickBooks references

[!TIP] Calculate the amount field correctly (quantity × unit price)

[!TIP] Test updates in sandbox environment before production

[!TIP] Handle sync token conflicts by re-fetching the latest PO data

[!TIP] Use sparse updates to only modify changed fields

[!TIP] Store the company ID to avoid repeated lookups

[!WARNING] Monitor QuickBooks API rate limits when performing bulk updates

[!TIP] Validate status transitions based on your QuickBooks workflow settings

[!TIP] Keep line numbers sequential for proper ordering in QuickBooks