Purchase Orders

📄️List Purchase Orders (list view)

Paginated purchase orders list using the list view trait. Supports full-text search, filters, sorting, and archival state.

📄️Create Purchase Order

Create a new purchase order with optional line items.

📄️Bulk Delete Purchase Orders

Bulk delete purchase orders by IDs or by filter criteria.

📄️List Purchase Orders (List)

Paginated purchase order list for the list view. Uses Spatie QueryBuilder with advanced grouped filter support.

📄️Export Purchase Orders

Export purchase orders as XLSX or CSV. Supports summary (one row per PO) and line_items (one row per line item with PO fields repeated) modes.

📄️List Export Columns

Returns the master registry of supported PO email CSV columns and the tenant-wide default selection. Used by the per-supplier CSV column picker, the supplier preferences panel, and the PO settings page.

📄️Get Purchase Order

Get a single purchase order with all relations loaded: lines, products, inventory, shipments, receipts, invoices, bills, notes, financial lines, Amazon inbound data, and more.

📄️Update Purchase Order

Update an existing purchase order. All fields are optional (sometimes).

📄️Delete Purchase Order

Delete a single purchase order. Fails with 400 if the PO has invoices (delete the invoices first) or has received inventory that has been used in FIFO layers.

📄️Bulk Approve Purchase Orders

Bulk approve purchase orders by IDs or filters.

📄️Bulk Submit Purchase Orders

Bulk submit (send to supplier) purchase orders.

📄️Bulk Archive Purchase Orders

Bulk archive purchase orders.

📄️Bulk Unarchive Purchase Orders

Bulk unarchive purchase orders.

📄️Check Purchase Orders Deletable

Check whether each purchase order can be deleted. Returns a list with deletable flag and reason if not.

📄️Submit PO to Supplier

Submit (send) a draft purchase order to the supplier. Triggers PO sent notification.

📄️Close Purchase Order

Manually close an open purchase order.

📄️Reopen Purchase Order

Reopen a closed purchase order.

📄️Duplicate Purchase Order

Duplicate a purchase order (creates a new draft with the same lines).

📄️Cover Backorders

Sync inventory allocation coverages for all lines in this purchase order.

📄️Generate Accounting Transaction

Generate (or regenerate) the accounting transaction for a purchase order.

📄️Create Receiving Discrepancy

Create an accounting transaction for the receiving discrepancy on this purchase order.

📄️Undo Receiving Discrepancy

Reverse a previous 'close with receiving discrepancy' on a purchase order. No request body.

📄️Mark as Opening-Balance Purchase Order

Mark a purchase order as an opening-balance ('transition') order. Use this for a purchase order whose stock was received before your inventory start date, so it was loaded as an opening balance rather than as tracked receipts. No request body.

📄️Remove Opening-Balance Mark

Remove the opening-balance mark from a purchase order and reopen it so its receipt status recomputes normally from actual received quantities. No request body.

📄️Get PO Lines

Purchase order lines for the PO grid (POGridView), plus the vendor-credit / lookup callers that pass limit=-1 to fetch every line. Includes per-line COGS breakdown data.

📄️Get PO Lines for Invoice

Get purchase order lines optimised for invoice creation. Returns only essential invoice-relevant fields with minimal N+1 overhead.

📄️Get PO Lines for Receiving

Lean endpoint for the Receive drawer. Returns only the 8 fields the UI consumes (id, sku, name, barcode, img_url, quantity, received) — no COGS, no allocations, no inventory snapshots, no resource transformation.

📄️Get PO Shipment Line Options

Lines for the Create Shipment / Add to Existing Shipment pickers on the PO Shipments tab.

📄️Get PO Line Items (Lightweight)

Lightweight line items for the expandable row in the list view. Returns id, product SKU, barcode, product_name, quantity, received_quantity, amount, discount_rate, and line_total.

📄️Import Lines from CSV

Import purchase order line items from a CSV file. CSV must have a 'sku' column. Optional columns: quantity, unit_cost, description, discount_rate, tax_rate_id, pricing_tier, barcode.

📄️Download Lines Import Template

Download an XLSX import template for PO line items with headers (sku, quantity, unit_cost) and sample data.

📄️Apply Discount Rate to Lines

Apply a discount rate to all lines of a purchase order.

📄️Apply Pricing Tier to Lines

Apply a supplier pricing tier to all (or specified) lines of a purchase order.

📄️Apply Tax Rate to Lines

Apply a tax rate to all lines of a purchase order.

📄️Clear Tax Rate from Lines

Clear tax rates from all lines of a purchase order.

📄️Update PO Line

Update a single purchase order line. Designed for the PO grid's inline-edit interactions (tax rate, quantity, unit cost, discount, description, FOC toggle, nominal code).

📄️Short-Close PO Line

Short-close a PO line at a smaller `closed_quantity` than originally ordered. Records an audit event (PurchaseOrderLineShortCloseEvent) and mutates the line's `quantity` to the new effective ordered amount. The line's own `save` propagates the change into demand-planning coverages.

📄️Undo Short-Close

Reverse a prior short-close event, restoring the PO line's original ordered quantity.

📄️Settle PO Line Billing (Final Invoice)

Mark a PO line as billing-settled — the SAP EREKZ 'final invoice' axis. A billing-settled line counts as fully invoiced for reconciliation regardless of any residual short-billed quantity; use it when the supplier confirms this is the final bill for the line even though it was under-billed.

📄️Unsettle PO Line Billing

Reverse a prior billing settlement on a PO line, clearing the SAP EREKZ 'final invoice' flag. The line reverts to normal quantity/credit reconciliation, so it may flip back to partially-invoiced if it was short-billed.

📄️Settle Whole PO Billing (Final Invoice)

Bulk-settle the billing axis for every eligible line on a purchase order in one call — the whole-PO equivalent of the per-line settle endpoint. Each still-open, short-billed line is stamped billing-settled; lines already fully invoiced or already settled are left untouched.

📄️Reorder Purchase Order Lines

Persist a new top-to-bottom ordering for a purchase order's lines.

📄️Get PO Receipts

Get all shipment receipts for a purchase order.

📄️Get Single PO Receipt

Get a single receipt for a purchase order.

📄️Get Dropship Shipments

Get dropship fulfillment shipments for a dropship purchase order. Returns empty array for non-dropship POs.

📄️Mark as Shipped (FBA/AWD)

Mark an FBA or AWD purchase order as shipped. Processes through Amazon inbound management (creates pending inbound record).

📄️Update Shipment Details (FBA)

Update shipment details (shipped date and tracking number) for an already-shipped FBA purchase order.

📄️Get Notes

Get paginated notes for a purchase order (most recent first).

📄️Add Note

Add a note to a purchase order.

📄️Toggle Note Pin

Toggle the pinned state of a note on a purchase order.

📄️Delete Note

Delete a note from a purchase order.

📄️List Purchase Order Communication Threads

List the topic threads on a purchase order (e.g. 'Ship date', 'Invoice'), most-recent first. Each thread includes its primary channel, unread count, and latest message for the sidebar preview.

📄️Create Purchase Order Communication Thread

Start a new topic thread on a purchase order and post its first message. For email threads the subject doubles as the email subject sent to the supplier. Attach files by sending the request as multipart/form-data with attachments[] parts.

📄️List Purchase Order Communications

List the vendor communication thread for a purchase order, newest first. The thread interleaves outbound emails, inbound supplier replies, internal notes, and system events.

📄️Create Purchase Order Communication

Post a message onto the purchase order's communication thread.

📄️Set Supplier WhatsApp/SMS Number

Set the linked supplier's WhatsApp/SMS number (E.164, e.g. +15551234567) so the messaging channels become usable on this purchase order without opening the supplier record. Send a blank value to clear the stored number. Returns the updated channel availability for this purchase order.

📄️Mark Communication as Read

Mark an inbound communication entry as read, clearing it from the unread count.

📄️List Supplier Communications (Cross-PO)

List every vendor communication for a supplier across all of their purchase orders, newest first. Read-only aggregate view; each item links to the purchase order it belongs to via link_route.

📄️Activity Log

Get paginated activity log for a purchase order. Covers events on the PO, its lines, and invoices.

📄️Inventory Movements

Get paginated inventory movements for a purchase order (via receipt lines).

📄️FIFO Layers

Get paginated FIFO inventory layers created from receiving this purchase order.

📄️List PO Invoices

Get paginated purchase invoices for a specific purchase order.

📄️Preview Invoice

Generate an invoice PDF preview and return the URL path.

📄️Create Bill

Create a landed cost bill linked to this purchase order.

📄️Get Bill

Get a single bill linked to this purchase order. Returns 404 if the bill does not belong to this PO.

📄️Update Bill

Update a bill linked to this purchase order. Returns 404 if the bill does not belong to this PO.

📄️Download Import Template

Download an XLSX import template with headers, sample data, field guide, and reference data.

📄️Preview Purchase Order Import

Preview a purchase order import file before executing. Returns a grouped preview of what would be imported.

📄️Validate Import

Validate mapped import rows and return a grouped preview with errors. No side effects — safe to call repeatedly.

📄️Import Purchase Orders

Execute the purchase order import — create purchase orders from validated data.

📄️Send ASN

Send an Advanced Shipment Notice (ASN) for this purchase order to the 3PL warehouse.

📄️Dropship (Ship Fulfillment)

Create a dropship fulfillment for a dropship purchase order (ship directly to customer).

📄️List Awaiting-Invoice POs

Paginated worklist of purchase orders still awaiting the supplier's invoice — invoice_status in (uninvoiced, partially_invoiced) AND submission_status in (submitted, finalized), not archived. Prepaid POs (a paid vendor deposit) are the priority to chase. Each row projects amount_paid (sum of paid vendor deposits) and age_days.

📄️Request Invoice (Single PO)

Email the supplier requesting the outstanding invoice for a single purchase order, optionally attaching vendor-deposit documents (e.g. proof of the prepayment). The reply-to is set to the sending user. On success the PO is stamped: invoice_requested_at = now, invoice_request_count incremented, invoice_last_requested_by = current user.

📄️Get Purchase Order Cash Flow Schedule

Get the purchasing cash-flow schedule — expected vendor payments derived from all open, non-archived purchase orders.

📄️List Expected Vendor Deposit Milestones

List the expected payment milestones for a purchase order, derived from its payment-term deposit schedule.

📄️Create Vendor Deposit from Milestone

Create a draft vendor deposit from a payment-term schedule milestone. No request body — the milestone key (from **List Expected Vendor Deposit Milestones**) fully identifies the action.

📄️Get Purchase Order Return Metrics

Get the annualized return (Annualized ROI / IRR) for a purchase order.

📄️Get Consignment Settlement Preview

For a consignment purchase order, list each line's consigned stock that has sold but has not yet been settled with the supplier, priced at the consignment cost. Lines with nothing left to settle are omitted.

📄️Create Consignment Settlement

Generate a settlement bill for a consignment purchase order, covering the consigned stock that has sold but not yet been settled. The bill is created for the supplier and the purchase order stays open so further sales can be settled later.

📄️Return Unsold Consigned Stock

Return unsold consigned stock to the supplier for a consignment purchase order. This removes the returned units from sellable stock; it creates no bill and no credit, because unsold consigned stock was never owed for. Returning stock also updates the purchase order's consignment settlement status, and a purchase order whose stock is now entirely sold-and-settled or returned is automatically closed.

📄️Share Consignment Settlement Report

Share a consignment settlement's Account Sales Report with the supplier. The report is term-aware — it states how much is owed and when it is due, derived from the consignment payment term on the purchase order.

📄️Get Consignment Statement of Account

A rolling balance-forward statement of account for a supplier's consignment settlements: opening balance, each settlement with amount / paid / outstanding and a running balance, and the closing balance. The summary also reports the consignment liability that has accrued from sales but has not yet been settled.

📄️Get Consignment Aging Settings

The consignment aging-alert configuration: whether aging alerts are sent, the age (in days on consignment) at which unsold consigned stock is flagged, and whether flagged stock is automatically returned to the supplier.

📄️Update Consignment Aging Settings

Update the consignment aging-alert configuration. All fields are optional; only the provided fields are changed.

📄️List Purchase Order Revisions

List the immutable revision snapshots captured for a purchase order, newest first. A snapshot is recorded every time the order is sent to the supplier, so this is the complete send history of the order.

📄️Get Purchase Order Revision

Retrieve a single purchase order revision snapshot with its full header and line detail. The snapshot is a frozen copy of the order as it was sent to the supplier for that revision.

📄️Get Changes Since Last Sent

Compare the live purchase order against the most recent revision snapshot and return a line-level and header-level diff. Use it to detect when an order has been edited after it was last sent to the supplier, so those pending changes can be reviewed and re-sent.

📄️Dismiss Pending Changes

Dismiss the pending post-send changes on a purchase order without re-sending it. Use this when an order was edited after it was sent but the change does not need to go to the supplier — the supplier keeps the last sent revision.

📄️List Supplier Responses

List the supplier responses recorded against a purchase order's sent revisions, newest first. A response captures how the supplier replied to a revision they received — accepting it, requesting changes, or rejecting it — optionally with per-line confirmed quantities, costs and dates.

📄️Record Supplier Response

Record a supplier's response to a sent purchase order revision. Use it to log that the supplier accepted the order, requested changes, or rejected it, optionally capturing the quantities, costs and dates the supplier confirmed for individual lines.

📄️Apply Supplier Confirmed Changes

Apply a `changes_requested` supplier response's confirmed line quantities back onto the live purchase order. Each confirmed quantity is written to its line, respecting the floors already received or invoiced on that line so committed quantities are never reduced below what has already happened.