Claude Skill

fluentcart-shipping-tax

Implements and audits FluentCart shipping zones, methods, classes, checkout address matching, tax classes/rates, inclusive and exclusive prices, compound and shipping tax, per-variation overrides, EU VAT validation, and reverse charge. Use when extending ShippingMethod, ShippingZ

LLM Mart · 0 points · 0 0 0

Virus-scanned Reviewed automatically before listing.

Full trust report

Download lonsdale201-wp-agent-skills-fluentcart_fluentcart-shipping-tax-52f6020.zip · 3 KB

lonsdale201/wp-agent-skills 22 2 forks MIT Updated 5d ago

Part of lonsdale201/wp-agent-skills — 226 skills

Install

skills CLI npx skills add https://github.com/Lonsdale201/wp-agent-skills/tree/main/fluentcart/fluentcart-shipping-tax

Claude Code

claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install lonsdale201-wp-agent-skills@llmmart

Git git clone https://github.com/Lonsdale201/wp-agent-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole lonsdale201/wp-agent-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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

Files (wp-agent-skills)

agents

openai.yaml 313 B

interface:
  display_name: "FluentCart shipping and tax"
  short_description: "Extend shipping and tax without trusting totals"
  default_prompt: "Use $fluentcart-shipping-tax to implement or audit this FluentCart shipping or tax flow with destination validation, server recalculation, and historical snapshots."

references

shipping-tax-pipeline.md 2.7 KB

# FluentCart 1.6.0 shipping and tax pipeline

## Checkout sequence

~~~text
server-owned cart lines
  -> current shipping/billing address
  -> applicable enabled zone methods
  -> validate selected method and calculate shipping
  -> resolve each line's effective tax class/inclusion mode
  -> destination tax rates, discounts, fees and shipping tax
  -> line/recurring/signup tax allocations
  -> cart/order totals and order-time tax snapshots
~~~

Shipping and tax must be recalculated together after any input that changes the
taxable base or destination.

## Core data

| Concern | Source |
|---|---|
| Shipping zones | fct_shipping_zones / ShippingZone |
| Methods and configured amount | fct_shipping_methods / ShippingMethod |
| Product shipping classes | fct_shipping_classes / ShippingClass |
| Tax class definitions | fct_tax_classes / TaxClass |
| Destination rates | fct_tax_rates / TaxRate |
| Historical applied rates | fct_order_tax_rates / OrderTaxRate |
| Product/variation calculation | TaxCalculator |
| Defaults, country maps and management | TaxManager and TaxModule |

ShippingMethod::getApplicableForCountry() includes the additional country-list
check required for zones whose region is selection. A raw query that only sees
the selection marker is insufficient.

## Address and selection trust boundary

The address is customer input, while configured zone membership, method state,
amount, class rules, tax settings and rates are server state. Re-resolve all of
them on checkout. A stored cart choice may become invalid after an address or
line-item change.

## Tax behaviors

TaxCalculator supports store defaults plus per-variation inclusion overrides.
Its tax_behavior values distinguish exclusive (1), inclusive (2), and mixed
(3). Mixed mode requires line-level interpretation; do not collapse it to the
current store default.

Compound taxes build on the current taxable amount plus earlier tax. Discounts
must reduce the correct taxable base before rate application. Subscription
lines additionally carry signup and recurring tax allocations.

## EU VAT extension checklist

1. Normalize country and VAT prefix without trusting the browser label.
2. Call a reliable validation provider with timeout and bounded retries.
3. Cache by normalized country/number for an appropriate short period.
4. Return the installed filter contract, not a guessed boolean.
5. Record enough order-time evidence for later invoice/audit use.
6. Recalculate and emit state changes only when reverse-charge status changes.
7. Test provider outage and ambiguous responses explicitly.

## Long-running processes

TaxCalculator keeps request memoization. Call resetCache() between simulated
requests, tenant/store switches, or fixture mutations in CLI workers and tests.

SKILL.md 5 KB

---
name: fluentcart-shipping-tax
description: >-
  Implements and audits FluentCart shipping zones, methods, classes, checkout
  address matching, tax classes/rates, inclusive and exclusive prices,
  compound and shipping tax, per-variation overrides, EU VAT validation, and
  reverse charge. Use when extending ShippingMethod, ShippingZone,
  TaxCalculator, TaxManager, TaxModule, fct_shipping_methods, fct_tax_rates,
  fluent_cart/tax/validate_eu_vat_number, checkout shipping selection, carrier
  quotes, taxable fees, or historical order tax snapshots.
metadata:
  wp-skills-author: "Soczó Kristóf"
  wp-skills-contact: "mailto:lonsdale201@hotmail.com"
  wp-skills-plugin: "fluent-cart"
  wp-skills-plugin-version-tested: "1.6.0"
  wp-skills-wp-version-tested: "7.0.2"
  wp-skills-php-min: "7.4"
  wp-skills-last-updated: "2026-08-06"
---

# 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](references/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