Lonsdale201 FluentCart shipping and tax
Treat shipping and tax as server-owned checkout calculations. A browser may select an available method and provide an address; it must not decide the method's eligibility, price, tax class, VAT result, or final total.
Read shipping-tax-pipeline.md before adding carrier quotes, destination rules, tax overrides, or reverse charge.
Resolve shipping from the current address
FluentCart stores zones, methods, and classes in its own tables. Use ShippingMethod::getApplicableForCountry() or the shipping module's services so selection zones are post-filtered by their country list and disabled/state- inapplicable methods disappear.
Revalidate a selected method whenever country, state, postal code, cart lines, shipping class, quantity, coupon, or store mode changes. Reject a stale method instead of preserving a client-submitted amount. Keep amounts in integer minor units.
Do not assume there is a stable abstract carrier-gateway SDK in 1.6.0. For live quotes, keep provider calls in an addon-owned service, normalize results into FluentCart's current shipping calculation contract, cache narrowly, enforce timeouts, and retain a deterministic failure/fallback policy.
Calculate tax through TaxCalculator
TaxCalculator resolves the effective product/variation tax class, destination rates, category/store fallbacks, discounts, fees, shipping tax, subscription signup/recurring amounts, inclusive/exclusive behavior, compound rates, and rounding. Do not append tax by editing cart or order totals after this pipeline.
Preserve these invariants:
- product variation overrides take precedence over category/default mappings;
- mixed inclusive/exclusive carts can have tax_behavior 3;
- store-level behavior still governs shipping and fee treatment;
- taxable fees need an explicit tax decision;
- line and aggregate rounding must remain internally reconcilable;
- tax-disabled and zero-rate outcomes are different states.
Call TaxCalculator::resetCache() in long-running workers/tests that simulate multiple stores or requests. Ordinary PHP requests get fresh in-memory caches.
Handle VAT and reverse charge defensively
fluent_cart/tax/validate_eu_vat_number may supply third-party validation. Return the exact shape expected by the installed TaxModule, validate country/prefix consistency, use bounded network timeouts and caching, and fail according to an explicit store policy. Never grant reverse charge solely because the submitted VAT string is syntactically valid.
Treat fluent_cart/tax/reverse_charge_line_adjustment as a calculation filter, not an authorization decision. Observe fluent_cart/tax/reverse_charge_applied and reverse_charge_removed for replay-safe side effects only.
Preserve historical evidence
Persisted order lines and OrderTaxRate records are order-time snapshots. Do not recalculate old invoices from today's TaxRate, product category, address, or shipping settings. Refunds must allocate from the stored order figures.
Test matrix
Test all/selection/country zones, state inclusion, no method, disabled method, shipping-class changes, free/paid shipping, quote timeout, stale selection, tax disabled, zero/reduced/standard classes, variation override, inclusive, exclusive and mixed carts, compound rates, taxable shipping/fees, fixed coupon rounding, subscription signup/renewal, EU B2B validation success/failure/ timeout, reverse-charge add/remove, zero-decimal currency, and historical order rendering after settings change.
Cross-references
- Use fluentcart-cart-checkout for checkout mutation and locking.
- Use fluentcart-products-inventory for variation/class data.
- Use fluentcart-orders-transactions for snapshots and refunds.
References
- Verified Free source paths:
- fluent-cart/app/Modules/Shipping/
- fluent-cart/app/Models/ShippingZone.php
- fluent-cart/app/Models/ShippingMethod.php
- fluent-cart/app/Models/ShippingClass.php
- fluent-cart/app/Modules/Tax/TaxModule.php
- fluent-cart/app/Modules/Tax/TaxCalculator.php
- fluent-cart/app/Services/Tax/TaxManager.php
- fluent-cart/app/Models/TaxClass.php
- fluent-cart/app/Models/TaxRate.php
- fluent-cart/app/Models/OrderTaxRate.php