Troubleshooting fees that do not apply, wrong amounts, and missing tax

A fee is not appearing in cart or checkout

Work through these in order - the first three cover most reports:

1. Module switch. Confirm Stores > Configuration > OrangeCollar > Extra Fees > Enable Extra Fees is Yes. The module ships disabled, and this switch silences every fee regardless of individual settings. Flush the cache after changing it.
2. Fee status. Confirm the fee’s Is Active is Yes (check the grid’s Active column - it is inline editable and easy to toggle accidentally).
3. Store scope. Confirm the fee’s Store Views selection includes the store view you are testing on, or is All Store Views. A fee scoped to one storefront is invisible everywhere else by design.
4. Schedule window. If Active From / Active To are set, confirm they cover the current date and time in that store view’s timezone - the window is store-local wall-clock time, not server time.
5. Condition values. Conditions store attribute option IDs, not labels. Open the product and confirm it actually carries the value; re-pick the value in the fee form’s dropdown to confirm the ID mapping. For configurable products, check whether the attribute lives on the parent or the child - both are evaluated, but the option ID must match whichever product carries the value.
6. Checkout-dependent conditions. Shipping country/region/postcode, shipping method, and payment method conditions never match until the quote has that data. They will not fire on the cart page, never fire on a virtual-only cart, and only fire once the shopper reaches the relevant checkout step. This is deliberate.
7. Optional fees. A fee with Is Optional = Yes appears only after the shopper checks its box in the checkout summary. Not a bug.
8. Multishipping. Fees are skipped entirely on multi-address checkouts, with a warning logged.

The fee amount looks wrong

• Percentage fees compute from the matching items only (qty x price excluding tax, pre-discount), not the whole cart subtotal.
• Fixed fees do not scale with quantity - $10 is $10 whether one or ten qualifying items are in the cart.
• If a percentage fee has Min/Max caps, check whether the amount is simply being clamped. Caps are base-currency and apply before tax.
• If Fee Amounts Include Tax is on, the entered amount already includes tax for taxable fees with an effective tax class - compare against the tax-exclusive figure after backing tax out, not the raw field value.
• On multi-currency stores, fixed amounts are entered in base currency and converted at the current rate; a “wrong” display amount is often just the conversion.

Tax is missing on a taxable fee

• Verify an effective tax class exists: the fee’s own Tax Class, or, if that is “Use Default (Configuration)”, the global Fee Tax Class in configuration. If neither resolves to a real class, taxable fees are not taxed - by design.
• Verify a tax rule actually applies to that class for the customer’s address.
• Look at the order’s Tax line: fee tax is rolled in there, never shown as a separate fee tax row.

The fee line shows a blank label

A blank fee label at cart or checkout is a symptom of running an old module version - update to 1.1.0 or later. On current versions a blank per-store label override simply falls back to the fee’s default Name/Label, so an empty label cannot reach the storefront.

Grid and export notes

• The grid’s Export button honors the filters currently applied - filter first to export a subset.
• The Conditions column shows stored option IDs (e.g. color == 91), not labels. That is the stored truth, not a rendering bug; labels can be renamed while IDs stay stable.
• The admin orders grid’s Extra Fees column is populated by core’s own grid refresh, so it is correct under both synchronous and async (cron) grid indexing. If it looks stale on an async store, the grid indexer cron has not run yet - the same lag every other grid column has.
• Fees created over the REST API apply to All Store Views until narrowed from the admin form; scope and per-store labels are not settable over the API.

Hyva storefronts

• The cart page fee line requires the companion ocmlabs/module-extra-fees-hyva module - the base module’s cart line is a Luma/Knockout jsLayout component that Hyva does not process. Without the companion module, fees are still charged and appear at checkout, they just do not render a line on the Hyva cart page.
• The checkout works through the standard Luma/Knockout checkout fallback, where fee lines and the optional-fee checkbox render natively. Native Hyva Checkout (Magewire) is not supported by the base module or the companion module.
• The optional-fee selection checkbox exists only in the Knockout checkout order summary. There is no Hyva-native selection UI; once selected at checkout, the fee line displays fine in the Hyva cart totals.

A view-only admin cannot save or delete

Expected: OCMLabs_ExtraFees::view is read-only. Save, mass enable/disable, and Duplicate need ::manage; delete and mass delete need ::delete. Adjust the role under System > User Roles.