Simulator deep-dive
The Simulator is a fake-cart playground in the admin sidebar (Simulator). It runs the exact same rules as your live storefront but without ever touching a real customer's session. Use it to test "would this rule fire on this cart?" while you're still configuring a campaign - or to debug "why didn't the rule fire on a customer's cart yesterday?" after the fact.
Two modes: Easy and Developer
At the top of the page is a mode toggle.
- Easy mode (default) - visual results. Build a cart, click Run Simulation, see which rule matched and which gift would be added. Best for the everyday "does this campaign work as expected" test.
- Developer mode - full diagnostic log. Adds a per-condition breakdown showing every condition's pass/fail with the values it compared against. Best when a rule isn't matching and you need to figure out which condition tripped.
You can switch modes at any time without losing your test cart.
Building a test cart
The cart-builder lets you add real products from your store (variant picker), set quantities, and attach a custom note to a line (for rules that match on a specific cart-line note). It mirrors what a real customer's cart would look like, plus a few knobs that aren't visible to a real customer:
- Customer identity - toggle "logged in" on/off. Set tags (e.g.
VIP,wholesale) to test customer-tag conditions. - Market & country - pick from the markets and currencies your store sells in. Used for country / market conditions and per-currency thresholds.
- Discount codes - paste a code to test conditions that check whether any code or a specific code is applied.
Reading the Easy-mode result
After Run Simulation, the results panel shows:
- Which rule matched (or "No rule matched"). If multiple rules match, each is listed.
- Which gift would be added - product name, variant, quantity.
- Health warnings if the matched rule has a problem the engine would flag at storefront-time too: gift product unavailable, gift variant deleted, trigger product also unavailable, campaign currently paused/scheduled/expired. Fix these before going live.
If "No rule matched," your conditions don't fit the cart you tested. Switch to Developer mode to see why.
Reading the Developer-mode trace
Developer mode adds a condition trace for each rule. Each condition shows a plain-English sentence plus the observed value from your test cart, color-coded green or red:
- Rule - the plain-English condition (e.g. "Cart subtotal is at least $50").
- Detail - what the cart actually had (e.g. "Currently $48.00").
- Pass / Fail - green check for matched, red cross for didn't.
The trace makes it obvious where a rule fails. Common patterns:
- "Cart subtotal must be at least $50" - Currently $48.00 → Fail. You set the threshold too high for this test cart.
- "Customer must have one of these tags: VIP" - Currently no matching tag → Fail. The test customer doesn't have the VIP tag - add it on the right panel.
- "Customer must be in country: Germany" - Currently in United States → Fail. Switch the market context to Germany.
When to use the Simulator vs other testing tools
Three test surfaces; each has a sweet spot.
| Tool | When to use |
|---|---|
| Simulator (admin sidebar → Simulator) | Testing rule logic without committing to anything live. Fastest. No real cart involved. |
| Preview URL (Preview button on the campaign edit page) | Testing how the rule behaves on your real storefront with a 24-hour signed link - only people with the link see the campaign. Catches theme-rendering issues the Simulator can't. |
?vltrx_debug=true on the live storefront | When the rule passed the Simulator + Preview but isn't firing for a real customer. The flag prints the same per-condition log as Developer mode, but on a real cart with the real theme. |
If a rule works in the Simulator but not in Preview, it's almost always a theme rendering issue. If a rule works in Simulator + Preview but not on the live store, it's almost always a customer-state difference (different market, logged-out vs logged-in, etc.) - ?vltrx_debug=true will show you the difference.
Plan-tier note
The full Simulator (Easy + Developer modes) is available on Growth plan and above. Free plan sees Easy mode only - Developer mode shows an upgrade prompt.