Extending MediaOpt Avalara for US Shopware: retail delivery fees and entity use codes

The MediaOpt Avalara plugin for Shopware 6 (MoptAvalara6) is a solid bridge to AvaTax for US and Canadian sales tax, address validation, and post-order commits. On a US-heavy Shopware program, we still needed two things the stock integration did not fully carry: state retail delivery fees (RDF) where Avalara returns them as tax on a dedicated line, and customer-level tax exemption driven by Avalara entity use codes so B2B and exempt buyers match what finance expects in AvaTax.

Companion plugin + surgical patches

We shipped a small static plugin, Avalara Enhanced (AvalaraEnhanced in the project repo), that layers configuration, admin UI, and PHP helpers on top of MoptAvalara6. Because several touch points sit deep in the vendor package—GetTax payload construction, response normalization, and cart price overwrite—we apply a Composer patch set to store.shopware.com/moptavalara6 so upgrades stay predictable: each patch is named, versioned with the dependency, and limited to the seams we actually need.

Retail Delivery Fee (RDF) for selected states

Some US jurisdictions impose a retail delivery fee that Avalara models as tax on a dedicated misc line (tax code OF400000), not as a generic line-item price in the catalog. Out of the box, the storefront still has to request that line in the GetTax document and surface the returned amount so checkout matches AvaTax and customer receipts.

Our RdfLineHelper builds an extra LineItemModel when RDF is enabled for the sales channel, the ship-to state is in a configurable allowlist (for example Colorado and Minnesota), and the cart still has taxable merchandise. The line uses number RDF, quantity one, zero extended amount, description “Retail Delivery Fee”, and a state-scoped item code such as RDF-MISC-CO or RDF-MISC-MN so Avalara can distinguish programs that share a common pattern but not identical rules.

Patches then wire that helper into MediaOpt’s transaction factories, ensure the RDF line participates in GetTax the same way as catalog lines, normalize the GetTax response so RDF taxes map cleanly to cart keys (including mirroring state-specific item codes back to the cart’s RDF line), and extend OverwritePriceProcessor so when AvaTax returns RDF tax, the shopper sees a separate order fee line instead of a silent total mismatch. Structured logging (with optional pretty-printing of Avalara JSON) makes finance and engineering reads of production traces far less painful.

Tax exemption via Avalara entity use codes

Exempt organizations are not “zero-rate tax rules” you fake in Shopware alone—they are Avalara entities with specific entity use codes that must flow to AvaTax on each calculation. We added a customer custom field (under a dedicated fieldset) that stores the chosen code, plus an admin action that calls AvaTax’s listEntityUseCodes API and syncs the result into both system config and the select options on that field. A MediaOpt config card patch exposes a “Sync entity use codes” control next to the credentials merchants already maintain.

A separate patch passes the selected entity use code through the vendor’s tax request path so GetTax reflects exemption the same way your Avalara account does in the console. That keeps checkout, committed documents, and audits aligned without duplicating exemption logic in Shopware rules.

Operator experience and upgrades

We also patched MediaOpt’s administration bundle to stop hiding global Shopware system cards on plugin settings pages—small, but it saves hours when debugging mail or search alongside Avalara. Cart validation hooks block checkout when Avalara marks a line as failed so customers do not pay against a broken tax response.

Rolling upgrades to MoptAvalara6 still require reconciling patches when the vendor touches the same files; we treat that as part of the Shopware maintenance window, not a surprise hotfix. If you are planning AvaTax + Shopware for US retail, RDF states, and exempt entities, bake that review into the same cadence as extension updates.

Irish Titan is a Shopware Platinum partner—see our profile on Shopware. US tax work ships with the same Titan-only delivery model: Irish Titan employees from our headquarters, not anonymous subcontractor benches.