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.

📄️Download Purchase Orders Export

Downloads a completed background export produced by Export Purchase Orders. The file name is the one reported in the export job's results.file field (also embedded in results.download_url).

📄️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.

📄️Preview Bulk Submit Purchase Orders

Preview what a bulk submit would do to the selected purchase orders before running it: which orders are email-format (their supplier is emailed immediately on submit) and which are Manual-format (marked Finalized without emailing). Orders that are not open are counted as ineligible and skipped by the bulk submit.

📄️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 a purchase order to the supplier and record it as submitted.

📄️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 one discount rate to every line 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

Mark a purchase order line as billing-settled. A billing-settled line counts as fully invoiced for reconciliation regardless of any residual short-billed quantity.

📄️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

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 AWD Receipt Assessment

Compare an AWD purchase order's unreceived quantity with Amazon's own AWD shipment record.

📄️Confirm AWD Receipt

Close an AWD purchase order as received from Amazon's AWD shipment record.

📄️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.

📄️Cancel (Unsend) Purchase Order Communication

Unsend an outbound communication that is still within its undo window (delivery_state='scheduled'). Recalls the message so it is never sent, and returns the entry with delivery_state='cancelled'.

📄️Activity Log

Get paginated activity log for a purchase order. Covers events on the PO, its product lines, its cost lines, and its 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. Omit `currency_id`/`currency_rate` to keep the bill's current currency; send them to change it.

📄️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 its destination third-party logistics (3PL) warehouse. The destination warehouse must be of type 3PL.

📄️Dropship (Ship Fulfillment)

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

📄️List Dropship Labels for Purchase Order

Returns the purchase order's current dropship label (with its event timeline), the full label history (newest first, including voided and replaced labels), whether a label can be requested now, and the supplier portal link.

📄️Create Dropship Label

Requests a dropship label for the purchase order — buy it now, or schedule the purchase for the date the order will be ready to ship (the label is bought at the configured purchase time on that date in the supplier's timezone).

📄️Quote Dropship Label Rates

Returns live carrier rates for shipping the purchase order from the supplier's dropship warehouse to the customer, for the given packages and ship date. Nothing is purchased. Use a returned `service_token` with Create Dropship Label to pin a service; omit it to buy the cheapest allowed rate.

📄️Update Dropship Label

Reschedules a scheduled label to a new ship date, or buys it immediately.

📄️Void Dropship Label

Voids a purchased label with the carrier (requesting a refund) or cancels a scheduled one before it is bought. Some carriers confirm refunds asynchronously, in which case the label moves to `void_pending` until confirmed. Only labels whose `is_voidable` is true can be voided.

📄️Resend Dropship Label to Vendor

Emails the purchased label (PDF attached) to the supplier's purchase order email again. Rate limited to 20 requests per minute.

📄️Download Dropship Label

Streams the label file (usually `application/pdf`, served inline). Multi-package labels have one file per package; choose it with `package` (zero-based; the label's `label_file_count` is the number of files). An index with no file returns 422 `invalid_state`.

📄️List Dropship Label Providers

Lists the connected shipping integrations that can buy dropship labels (Shippo, ShipStation, Starshipit, EasyPost). Each item carries `integration_name` (the integration's display name) and `image_url` (relative path to the provider logo, null when the provider has none). `services` lists the integration's synced service levels where the integration keeps them (Shippo, ShipStation); an empty array means rates are shopped across every service the account offers. Use an `id` here as a supplier's `dropship_label_integration_instance_id` or the account default in Dropship Label Settings, and a service `token` in a supplier's `dropship_label_allowed_services`.

📄️Regenerate Supplier Portal Link

Rotates the purchase order's supplier portal link. Every previously sent link stops working immediately; send the new URL to the supplier.

📄️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.

📄️Resync Vendor Deposit with Milestone

Resolve an out-of-sync schedule milestone by realigning its linked vendor deposit with the milestone's current state — the one-click alternative to deleting and recreating the deposit.

📄️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.

📄️List Purchase Order Duty Estimates

Returns the estimated customs duty for each product line of a purchase order (the order is treated as one customs entry), with a summary: rate date, destination country, who clears import, currencies and totals.

📄️Recalculate Purchase Order Duty Estimates

Recalculates every duty estimate of the purchase order now, regardless of staleness, and returns the same payload as List Purchase Order Duty Estimates. Manual overrides are kept.

📄️Override Duty Estimate

Sets a manual duty amount (base currency) on a purchase order or inbound shipment duty estimate, replacing the calculated total; status becomes `overridden`. The override is carried forward pro rata to later stages (shipment, then receipt) until cleared. Send `override_amount: null` to clear it and restore the calculated estimate.