Troubleshooting

Start with the simulator

Before anything else, open Free Ride → Simulator — or run php craft freeride/simulate/order <number> — with the cart in question. It lists every rule in order, whether it was considered, and every condition with a ✓ or ✗. It reads the same decision checkout does, so whatever it says is what the customer got.

Free shipping didn't appear

Work down this list:

Is the rule enabled, and in the right store? Rules belong to a store; the Rules screen shows one store at a time.
Is it skipped? The simulator says Disabled, Not enabled for this site, or Outside its date window. Date windows are judged in the system timezone.
Did a block rule match? A block vetoes everything below and above it. The simulator's headline says Blocked by ….
Is there a customer condition on a guest cart? Any customer condition fails without a logged-in customer — the trace says No customer on the order yet.
Is the address there yet? See below.

Address conditions fail on the cart page

Postal code, country and state conditions need a shipping address. Before checkout there usually isn't one, so Free Ride uses Commerce's estimated shipping address when Use estimated addresses is on (the default). If your cart page doesn't set an estimated address, or that setting is off, address conditions have nothing to read until the customer enters a real one.

Watch the negative operators here. With no address at all, is not one of passes — so a block rule "postal code is not one of 28*" won't fire on an addressless cart, and a granting rule with that condition will match it. Pair a negative address condition with a positive one, like Shipping Country is one of United States, when that matters.

The progress message says nothing

That's usually deliberate. Progress only reports a distance when exactly one condition on a granting rule failed and it's a threshold the customer can cross. It stays silent when:

More than one condition failed. A cart under $50 and outside the postal codes isn't "$12 away" — spending $12 wouldn't get it there.
The failing condition isn't a threshold. A coupon code, a product type or a postal code isn't something the customer can top up.
The operator points the wrong way. Is less than or is equal to has no "more to go".
A block rule matched. No amount of spending helps.

The simulator shows which of those applies.

A condition shows "Could not be evaluated"

A condition that throws — a deleted element it pointed at, a bug in a third-party condition — fails closed rather than taking checkout down with it. The simulator shows the message, and the full error is in Craft's logs (storage/logs/web-*.log), as Free Ride condition <class> threw: …. Fix or remove the condition; until then the rule simply doesn't match.

The paid methods still show with "Hide other shipping methods" on

Hiding only happens when that rule is the first granting rule to match. If a waiver or another method rule above it matches first, it decides. Move the rule up, or check its conditions in the simulator.

Customers are charged tax on waived shipping

They shouldn't be — the waiver runs directly after Commerce's shipping adjuster, before tax. If you see it, another plugin has likely reordered the adjuster list. Email the order's adjustments and your plugin list.

Logging every decision

Turn on Log decisions while you set up. Each evaluation writes one line to the freeride log category — Order <number>: free via freeOver50, blocked by noOversize, or no free shipping. These are info-level messages, so Craft only records them when its log level includes info, which it does in dev mode. Turn it off again once you're done — a busy store evaluates often.

Rules vanished after a deploy

They didn't deploy. Rules are in the database, not project config. Use freeride/rules/export and freeride/rules/import — see Configuration.

Getting help

Email justin@justinholt.com with the output of php craft freeride/simulate/order <number> for an order that surprised you, and php craft freeride/rules/export for the store.