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.
Who does what across the stack
Each component maintains a strict single responsibility boundary to prevent race conditions and out-of-sync inventory numbers.
Movex
ERP where purchase orders (POs) originate and expected inventory is created. Has zero concept of Shopify or preorder rules.
Barrett
Physical warehouse. Receives and checks in physical shipment units against open POs.
Techsera
Integration middleware. Responsible for writing inventory deltas and PO signal triggers into Shopify.
Shopify
Tracks available vs committed stock natively. Holds and releases fulfillment orders on inventory adjustments.
STOQ
Decides preorder button eligibility, applies checkout holds, and strictly enforces the customer sell limit.
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.