How a preorder becomes a real order
Four scenarios covering how Movex, Barrett, Techsera, Shopify, and STOQ stay in sync — from a purchase order landing in the ERP to customer delivery.
New PO arrives in Movex
backorder.incoming_po_quantity metafield via Shopify's GraphQL API (metafieldsSet) — this value is set/overwritten each time, not accumulated. It exists only to carry this one PO's quantity and trigger the next step.View GraphQL Request Payload
# Definition ID: gid://shopify/MetafieldDefinition/214024749169 mutation SetIncomingPOQuantity($metafields: [MetafieldsSetInput!]!) { metafieldsSet(metafields: $metafields) { metafields { id namespace key value type } userErrors { field message code } } } # GraphQL Variables: { "metafields": [ { "ownerId": "gid://shopify/ProductVariant/{{variant_id}}", "namespace": "backorder", "key": "incoming_po_quantity", "value": "100", "type": "number_integer" } ] }
preorder_max_count is read for that variant — the update endpoint sets an absolute value, so the current limit has to be queried first.current limit + incoming PO quantity.The preorder limit immediately reflects incoming stock. Physical inventory and order holds are completely untouched at this stage.
The metafield itself is transient — it only exists to trigger this sequence; the real accumulated value lives in STOQ's preorder_max_count.
Stock arrives, covers preorders & leaves surplus
delta via GraphQL (inventoryAdjustQuantities).prior <= 0 and current > 0). Queries held fulfillment orders, filters specifically by heldByApp.id (STOQ holds only — never a blanket release to avoid payment holds), and releases them.limit = count + units_in_transit − preorders_waiting (or reset count to 0, limit = units_in_transit). Correctly removes surplus units from the preorder quota so they sell as regular stock.• Arrival: PO of 100 units arrives (covers 50, leaves 50 surplus)
• In-Transit: Only PO#2 (80 units) remains, 0 waiting
• New Limit:
50 + 80 − 0 = 130 (or reset count to 0, limit = 80)• Result: Open spots = 80 (excludes the 50 surplus units now selling as regular stock).
When a shipment leaves a surplus, recalculating ensures the preorder quota reflects only remaining in-transit POs, avoiding over-selling.
Stock arrives & is fully absorbed (no surplus)
inventoryAdjustQuantities.0 because all incoming units are allocated to existing held orders.heldByApp.id). Pending orders remain held.If a shipment gets fully absorbed by held preorders (nothing left over), do nothing — the math already holds whether shipments arrive all at once or in partial deliveries.
PO registered on an in-stock item
backorder.incoming_po_quantity metafield via Shopify GraphQL (metafieldsSet).
• If stock sells out first: Transitions seamlessly into preorder with the staged limit ready.
• If PO arrives first: Scenario 2's surplus formula (limit = count + in_transit − waiting) recalculates upon receipt, stripping arrived units and preventing inflation.
Summary of the 4 Scenarios
The first two only ever affect the preorder limit. The next two only ever affect what happens to orders already on hold — never both at once.
Preorder Limit Increment
Movex PO → Techsera writes backorder.incoming_po_quantity → Flow → STOQ Limit (+PO Qty).
Hold Release & Surplus Recalc
Barrett receipt → Techsera delta → Flow releases heldByApp.id → STOQ recalculates limit (count + in_transit − waiting).
Partial Hold Release (Absorbed)
Committed drops by arrival count. Flow releases covered holds. Limit untouched because shipment is 100% absorbed (0 surplus).
Pre-staged In-Stock Limit (Resolved)
PO arrives while in-stock. Limit staged via unified formula, sits inert with zero UX impact until stock hits 0.
What's confirmed, what's open
Engineering validation status as of latest integration checks (STOQ & Architecture confirmations).
Shopify native available/committed math handles Flows 2 and 3
Nothing needs to be custom-built to track allocation — this is built-in Shopify inventory functionality.
Shopify Flow "Send HTTP request" can call STOQ API directly
Confirmed by STOQ support — custom headers (X-Auth-Token), external endpoints, and JSON payloads fully supported.
Metafield trigger & definition created in Shopify
Definition ID: gid://shopify/MetafieldDefinition/214024749169 (backorder.incoming_po_quantity, type number_integer). Techsera writes incoming PO quantities via metafieldsSet, and the installed Workflow Trigger Extensions app detects changes to trigger Shopify Flow.
reset_preorder_count is 100% safe with pending orders
Confirmed: STOQ's reset endpoint only clears the counter integer and never touches, modifies, or cancels active customer fulfillment holds.
Unified Surplus Recalculation Model
If a shipment is fully absorbed, limit is untouched. If it leaves a surplus, recalculate: limit = count + units_in_transit − preorders_waiting (or reset count to 0, limit = units_in_transit).
In-transit PO visibility & surplus detection per shipment
Whether Techsera/Movex can expose, at any point in time, how many units remain in transit across outstanding POs and whether a given shipment left a surplus — depends on whether POs typically arrive as a single complete shipment or in partial deliveries (pending business/ERP-side confirmation).
Fulfillment-hold release flow testing
Flow designed (filtering holds by heldByApp.id) — requires a clean rebuild and staging test before production go-live.
Capacity consideration: Workflow Trigger Extensions Free Tier
The Free plan includes a ceiling of 5,000 trigger events / month. Not an immediate blocker for launch, but an operational metric to monitor as catalog updates and PO volume scale.