Skip to main content

Preview Bulk Allocate Sales Orders

POST 
/api/sales-orders/bulk-allocate/preview

Previews a bulk allocate action without changing any data. For each targeted sales order the response reports per-line eligibility, the quantities involved, and the allocation impact, plus aggregate totals — use it to confirm what a bulk allocate will do before running it.

Required scope: orders:write

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

Authentication: Requires Bearer token.

Request body fields (one of ids or filters is required):

  • ids (array of integers, required without filters): Sales order IDs to target. Each ID must exist.
  • filters (object or string, required without ids): Resolves to the matching sales order IDs — the same targeting the sales-orders list uses. Two shapes are accepted:
    • Grouped filters: { "filter_groups": "<base64-encoded JSON tree>" }. The decoded tree looks like {"conjunction":"and","children":[{"type":"condition","condition":{"column":"order_status","operator":"is","value":"open"}}]}.
    • Legacy filter set (JSON string) for older clients.

Response fields:

  • orders[] — one entry per targeted order:
    • sales_order_id (integer), sales_order_number (string)
    • status (string|null): Raw status value of the order, when available.
    • eligibility (string): eligible, partially_eligible, or ineligible.
    • reason (string|null): Populated only when the order is ineligible, with the shared line-level reason or an order-level summary.
    • lines[] — one entry per warehoused product line:
      • sales_order_line_id (integer), product_sku (string|null), product_name (string|null), warehouse_name (string|null)
      • eligible (boolean), reason (string|null)
      • processable_quantity (integer): Ordered quantity net of cancellations.
      • fulfilled_quantity (integer): Quantity already committed to non-cancelled fulfillments.
      • currently_allocated (integer): Units already covered by active allocations.
      • impact_quantity (integer): Units this action would change on the line.
  • totals — orders_total, orders_eligible, orders_partially_eligible, orders_ineligible, lines_total, lines_eligible, lines_impact_quantity (all integers).

Behavior notes:

  • Only lines stocked in warehouses that track inventory allocations are considered; lines in warehouses that do not are reported with reason "Warehouse does not require inventory allocation".
  • Lines already fully allocated or fulfilled are ineligible with reason "Already fully allocated or fulfilled".
  • impact_quantity is the remaining unallocated demand that a bulk allocate would newly allocate.

Requires permission: sales_orders.update

Request​

Responses​

OK

Response Headers
    Content-Type