Four rules govern the plugin. Each one is there because fee plugins fail in a way a shop owner does not notice until a customer does.
The flow, on every recalculation
WooCommerce works the cart total out several times during one checkout — on the cart page, on every address change, on every coupon, on every change of shipping method. Each time, it clears its list of fees and fires woocommerce_cart_calculate_fees. The plugin listens there (priority 20) and:
- Reads the cart once — the goods (the lines' subtotal before coupons, shipping and tax), the shipping total, the tax, the number of items, and the shipping country (billing country if there is no shipping address). The full edition also reads the chosen payment method, the chosen shipping methods, the customer's roles, and — only if a rule asks — the categories and shipping classes in the cart.
- Takes each active rule in your order and checks its conditions.
- Works out the amount for every rule that matches.
- Adds the insurance charge if the shopper ticked the box.
- Adds each charge with
WC_Cart::add_fee(), skipping any that come to nothing.
Nothing is remembered between passes. That is the first rule.
The recompute rule
A fee is worked out on every pass and never carried forward. A plugin that stores an amount and adds it back on the next pass doubles the charge on the first AJAX cart update and trebles it on the second. Here the fee is a function of the cart as it stands, so it follows the cart: add items until a "small order" rule no longer applies and the line disappears.
The every-condition rule
Every condition on a rule must be satisfied — not the first one, not any one of them. A merchant who adds a second condition means "and", and adding a condition should only ever narrow who pays.
Rules do not compete. Every rule that matches charges, so two matching rules are two fee lines on the total.
A condition the plugin does not understand is false. If a rule carries a condition type nothing on this site can judge — one an extension declared and then stopped answering, or one only the full edition offers, read by the free edition — the rule does not charge. The condition is kept in storage rather than dropped, because dropping it would quietly widen the rule to everybody. A fee that stops appearing is something you notice; a fee that starts appearing for everybody is something your customers notice first.
The base rule — Full edition
A percentage has to say what it is a percentage of. The full edition makes every percentage rule choose:
- the goods after coupons, before shipping and tax — usually right for a handling fee;
- the goods after coupons and the shipping, before tax;
- everything the customer pays after coupons, tax included — right for a card surcharge, because the gateway takes its cut of the whole payment.
Worked example: a 1.4% card surcharge
A cart holds goods worth 100.00, shipping is 10.00 and tax on both comes to 22.00. The customer pays 132.00 before the surcharge.
| Measured against | Base | 1.4% |
|---|---|---|
| the goods | 100.00 | 1.40 |
| the goods and the shipping | 110.00 | 1.54 |
| everything the customer pays | 132.00 | 1.85 |
Measured against the goods alone, the shop recovers 1.40 of a fee charged on 132.00 — short by the shipping and the tax on every order. To write the rule:
- Charge: A percentage. Of:
1.4. - Measured against: everything the customer pays, tax included.
- When: The chosen payment method is one of, value
stripe(your card gateway's id).
The result is rounded to your shop's price decimals. The surcharge itself is not part of its own base.
Every base is measured after coupons — the lines as WooCommerce will charge them. A surcharge on a discounted cart is worked out on what the customer actually pays, not on the price before the coupon. (Conditions such as "the goods are worth at least" still read the subtotal before coupons.)
Discounts
A negative amount is a discount: A percentage, -2, measured against the goods, with The chosen payment method is one of bacs gives 2% off for bank transfer. WooCommerce never lets negative fees take the cart total below zero.
Which payment method?
When the shopper has not chosen one yet, the full edition reads the first available gateway, because that is the one the checkout selects and bills through if nothing is changed. Otherwise a surcharge would appear only after the shopper clicked the option that was already selected.
A fee is a fee, not a product
Charges are WooCommerce fees, never a "Handling" product in the cart. A product would show up in your stock report, your product feed, your sales-by-product report and "customers also bought". A fee is shown natively by the classic cart, the Cart and Checkout blocks, the Store API and every email, and lands on the order as a fee line.
Fees are not added on an ordinary admin recalculation of an order, because the session data there belongs to the last shopper, not to that order.
The opt-in rule: shipping insurance
Insurance is a tick box on the cart and the checkout — in the totals table on the classic pages, in the order summary on the Cart and Checkout blocks — with its price named beside it. It is never ticked for the shopper and there is no setting to tick it: a charge nobody asked for is a chargeback.
- The shopper ticks the box and presses Update cart (or the checkout refreshes on its own). On the classic pages the choice rides WooCommerce's own cart form and checkout refresh — no extra script. On the blocks, one small script sends the tick through WooCommerce's own cart-update request (Store API
cart/extensions), and the cart is recalculated straight away. - The choice is kept in the WooCommerce session (
gmfe_insured). - The charge is added as a fee on every recalculation while the box stays ticked.
- When the order is placed, three facts are written onto it: that it was insured, the amount as it was charged, and the value of the goods it covered.
- The choice is forgotten on the thank-you page and when the cart is emptied, so the shopper's next order does not arrive insured.
Both order screens then show a Shipping insurance box: "Insured for …" and "Charged: …", or "This order was not insured." Weeks later, when a parcel has gone missing, that record answers the question without anybody recalculating anything.
Full edition: the price is the flat amount plus a percentage of the goods, never less than the floor you set. A percentage alone charges almost nothing on a small parcel; a flat amount alone charges the same for a 3.00 parcel as for a 3,000.00 one.
The free edition and the full edition's rules
Both editions read the same gmfe_rules option. The free edition charges a rule only when it is one its own screen could have written: a flat, non-negative amount with at most one of its five conditions. Anything else — a percentage, a discount, several conditions, a payment-method condition — is kept exactly as it is and not charged. Not charging is the safe direction: a shopper is never billed under configuration the merchant cannot see on the screen in front of them.
