Skip to main content

List Purchase Orders (List)

GET 
/api/purchase-orders/list

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

Required scope: purchase-orders:read

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Authentication: Requires Bearer token.

Supports both simple filters (filter[field]=value) and advanced grouped filter trees (filter_groups). The advanced system supports AND/OR conjunctions with nested groups.

Available text filter columns: purchase_order_number, order_status, submission_status, confirmation_status (derived supplier-confirmation state; values: awaiting, confirmed, changes_requested, rejected), receipt_status, shipment_status, invoice_status, tracking_number, supplier_notes, submission_format, requested_shipping_method, po_type (standard/dropship/fba_inbound/awd_inbound), supplier_name, destination_warehouse_name, currency_code, payment_term, incoterm, shipping_method, supplier_email, supplier_po_email, supplier_company, supplier_contact, supplier_phone, supplier_address, supplier_city, supplier_province, supplier_zip, supplier_country, destination_email, destination_company, destination_phone, destination_address, destination_city, destination_province, destination_zip, destination_country, item_sku, item_name, item_nominal_code, item_supplier_sku, shipment_tracking, shipment_shipping_method, tag, invoice_number

Available numeric filter columns: supplier_id, destination_warehouse_id, id, total_quantity, total, tax_cost, product_total, additional_cost, discount, line_item_count, item_quantity, item_price, item_received, item_tax_rate, shipment_quantity, shipment_received, irr, sell_through

Available date filter columns: purchase_order_date, other_date, estimated_delivery_date, created_at, updated_at, fully_received_at, asn_last_sent_at, item_eta, shipment_date

Logistics tracking date filter columns: logistics_<slug>_estimate, logistics_<slug>_actual — where <slug> is the slug of any active LogisticsTrackingField (e.g. logistics_port-arrived_estimate, logistics_customs-cleared_actual). Each PO row in the response includes a logistics_tracking_field_values array with { slug, name, estimate_date, actual_date } entries for every active logistics tracking field configured for the tenant.

The irr and sell_through numeric filters match against the purchase order's annualized internal rate of return and sell-through, entered as whole percentages (e.g. irr greater_than 50 = an IRR above 50%, sell_through less_than 25 = under 25% sold through). They filter on the persisted product-variant return metrics; purchase orders without computed return metrics are excluded when either filter is used.

Return metrics (per PO, whole percentages; null until computed / not meaningful): sell_through = product-variant sell-through (units sold ÷ received × 100), irr = annualized internal rate of return (× 100). Filter on them with the irr / sell_through numeric filters above.

Request​

Responses​

OK

Response Headers
    Content-Type