claude-plugin-wordpress-manager 1.7.1 → 1.8.0

package/skills/wp-woocommerce/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: wp-woocommerce
+description: |
+  This skill should be used when the user asks to "manage products", "check orders",
+  "create a coupon", "view sales report", "WooCommerce setup", "configure shipping",
+  "manage WooCommerce store", "product catalog", "inventory management",
+  "order fulfillment", or any WooCommerce e-commerce operations.
+version: 1.0.0
+---
+
+## Overview
+
+Comprehensive WooCommerce store management via the WP REST Bridge WC tools (30 MCP tools using the `wc/v3` namespace). Covers product catalog CRUD, order lifecycle, customer management, coupon marketing, sales analytics, and store configuration (payments, shipping, taxes).
+
+## When to Use
+
+- User mentions WooCommerce, products, orders, coupons, or store management
+- User needs sales reports, revenue analytics, or top-selling products
+- User wants to configure payment gateways, shipping zones, or tax classes
+- User needs to manage WooCommerce customers or process refunds
+- User asks about WooCommerce extensions or system status
+
+## Prerequisites
+
+WooCommerce credentials must be configured in `WP_SITES_CONFIG`:
+
+```json
+{
+  "id": "myshop",
+  "url": "https://myshop.com",
+  "username": "admin",
+  "password": "xxxx xxxx xxxx xxxx",
+  "wc_consumer_key": "ck_xxxx",
+  "wc_consumer_secret": "cs_xxxx"
+}
+```
+
+Generate Consumer Key/Secret in WooCommerce > Settings > Advanced > REST API.
+
+## Detection
+
+Run the detection script to check WooCommerce presence:
+
+```bash
+node skills/wp-woocommerce/scripts/woocommerce_inspect.mjs
+```
+
+## WooCommerce Operations Decision Tree
+
+1. **Product management?**
+   - List/search products → `wc_list_products`
+   - Create product → `wc_create_product`
+   - Update product → `wc_update_product`
+   - Delete product → `wc_delete_product`
+   - Categories → `wc_list_product_categories`
+   - Variations → `wc_list_product_variations`
+
+2. **Order management?**
+   - List/filter orders → `wc_list_orders`
+   - Order details → `wc_get_order`
+   - Update status → `wc_update_order_status`
+   - Add note → `wc_create_order_note`
+   - Process refund → `wc_create_refund`
+
+3. **Customer management?**
+   - List/search customers → `wc_list_customers`
+   - Customer details → `wc_get_customer`
+   - Create customer → `wc_create_customer`
+   - Update customer → `wc_update_customer`
+
+4. **Marketing/Coupons?**
+   - List coupons → `wc_list_coupons`
+   - Create coupon → `wc_create_coupon`
+   - Delete coupon → `wc_delete_coupon`
+
+5. **Analytics/Reports?**
+   - Sales summary → `wc_get_sales_report`
+   - Top products → `wc_get_top_sellers`
+   - Order totals → `wc_get_orders_totals`
+   - Product totals → `wc_get_products_totals`
+   - Customer totals → `wc_get_customers_totals`
+
+6. **Store configuration?**
+   - Payment gateways → `wc_list_payment_gateways`
+   - Shipping zones → `wc_list_shipping_zones`
+   - Tax classes → `wc_get_tax_classes`
+   - System status → `wc_get_system_status`
+
+## Recommended Agent
+
+For complex multi-step WooCommerce operations, use the `wp-ecommerce-manager` agent.
+
+## Additional Resources
+
+### Reference Files
+
+- **`references/product-management.md`** — CRUD products, variations, bulk operations, image management
+- **`references/order-workflow.md`** — Order lifecycle, status transitions, notes, refunds
+- **`references/analytics-reports.md`** — Sales reports, KPIs, date ranges, export strategies
+- **`references/coupon-marketing.md`** — Coupon strategies, discount types, usage limits
+- **`references/shipping-setup.md`** — Shipping zones, methods, classes, flat rate/free shipping
+- **`references/payment-gateways.md`** — Gateway configuration, test mode, supported providers
+- **`references/tax-configuration.md`** — Tax classes, rates by country, automated tax services
+- **`references/wc-extensions.md`** — Popular extensions, compatibility, WC Marketplace
+
+### Related Skills
+
+- `wp-deploy` — Deploy WooCommerce store changes to production
+- `wp-audit` — Audit WooCommerce store security and performance
+- `wp-backup` — Backup WooCommerce database and uploads

package/skills/wp-woocommerce/references/analytics-reports.md

@@ -0,0 +1,75 @@
+# Analytics and Reports
+
+WooCommerce provides built-in reporting endpoints for sales performance, product popularity, and store-wide totals. Reports support predefined periods and custom date ranges, enabling both quick snapshots and historical trend analysis.
+
+## MCP Tools
+
+| Tool | Usage |
+|------|-------|
+| `wc_get_sales_report` | Sales totals: revenue, orders, items, tax, shipping, discounts |
+| `wc_get_top_sellers` | Top-selling products ranked by quantity sold |
+| `wc_get_orders_totals` | Order counts grouped by status |
+| `wc_get_products_totals` | Product counts grouped by type |
+| `wc_get_customers_totals` | Customer counts (total, paying, returning) |
+
+## Sales Report Fields
+
+`wc_get_sales_report` returns:
+
+| Field | Description |
+|-------|-------------|
+| `total_sales` | Gross revenue including tax and shipping |
+| `net_sales` | Revenue after discounts, before tax |
+| `average_sales` | Average daily sales for the period |
+| `total_orders` | Number of orders placed |
+| `total_items` | Total items sold |
+| `total_tax` | Total tax collected |
+| `total_shipping` | Total shipping charged |
+| `total_discount` | Total discounts applied |
+| `total_customers` | Unique customers in period |
+
+## Period Options
+
+```json
+// Predefined periods
+{ "period": "week" }      // Last 7 days
+{ "period": "month" }     // Current calendar month
+{ "period": "last_month" } // Previous calendar month
+{ "period": "year" }      // Current calendar year
+
+// Custom date range
+{ "date_min": "2026-01-01", "date_max": "2026-01-31" }
+```
+
+## Common Report Procedures
+
+### Monthly Sales Summary
+
+1. `wc_get_sales_report` with `period: "month"`
+2. `wc_get_top_sellers` with `period: "month"` — limit 10
+3. `wc_get_orders_totals` — check processing vs completed ratio
+4. Calculate KPIs from returned data
+
+### Year-over-Year Comparison
+
+1. `wc_get_sales_report` with `date_min: "2026-01-01"`, `date_max: "2026-12-31"`
+2. `wc_get_sales_report` with `date_min: "2025-01-01"`, `date_max: "2025-12-31"`
+3. Compare `total_sales`, `total_orders`, `total_customers`
+
+## KPI Formulas
+
+| KPI | Formula |
+|-----|---------|
+| Average Order Value (AOV) | `net_sales / total_orders` |
+| Revenue per Customer | `net_sales / total_customers` |
+| Items per Order | `total_items / total_orders` |
+| Discount Rate | `total_discount / total_sales * 100` |
+| Tax Rate | `total_tax / net_sales * 100` |
+
+## Tips and Gotchas
+
+- **Report data lag**: WooCommerce reports reflect order data at time of query; very recent orders may not appear immediately in aggregated totals.
+- **Status filter**: By default, reports include `completed` and `processing` orders. Cancelled/refunded orders are excluded from sales totals.
+- **Top sellers by quantity**: `wc_get_top_sellers` ranks by units sold, not revenue. Cross-reference with product prices for revenue ranking.
+- **Custom ranges**: When using `date_min`/`date_max`, the format must be `YYYY-MM-DD` — no time component.
+- **Export**: WooCommerce REST API does not provide CSV export; format results as markdown tables or pipe to a file for client-facing reports.

package/skills/wp-woocommerce/references/coupon-marketing.md

@@ -0,0 +1,92 @@
+# Coupon and Marketing
+
+WooCommerce coupons enable flexible discount strategies: percentage off, fixed cart discounts, and fixed product discounts. Coupons support usage limits, product/category restrictions, and customer-specific targeting for targeted marketing campaigns.
+
+## MCP Tools
+
+| Tool | Usage |
+|------|-------|
+| `wc_list_coupons` | List all coupons with current usage counts |
+| `wc_get_coupon` | Get full coupon details including restrictions |
+| `wc_create_coupon` | Create a new coupon with discount rules |
+| `wc_delete_coupon` | Delete a coupon permanently |
+
+## Discount Types
+
+| Type | Effect |
+|------|--------|
+| `percent` | Percentage off cart total (e.g., 20% off) |
+| `fixed_cart` | Fixed amount off the cart (e.g., $10 off) |
+| `fixed_product` | Fixed amount off each qualifying product |
+
+## Coupon Configuration Fields
+
+```json
+{
+  "code": "WELCOME20",
+  "discount_type": "percent",
+  "amount": "20",
+  "individual_use": true,
+  "usage_limit": 1,
+  "usage_limit_per_user": 1,
+  "minimum_amount": "50.00",
+  "maximum_amount": "500.00",
+  "product_ids": [],
+  "excluded_product_ids": [],
+  "product_categories": [],
+  "excluded_product_categories": [],
+  "email_restrictions": ["customer@example.com"],
+  "date_expires": "2026-12-31T23:59:59"
+}
+```
+
+## Marketing Strategies
+
+### Welcome Discount
+
+New subscriber or first-purchase incentive:
+- `discount_type: "percent"`, `amount: "15"`, `usage_limit_per_user: 1`
+- Set `individual_use: true` to prevent stacking
+
+### Cart Abandonment Recovery
+
+Sent via email automation to customers with abandoned carts:
+- `discount_type: "fixed_cart"`, short expiry (`date_expires`: 48–72 hours out)
+- Single-use per customer: `usage_limit_per_user: 1`
+
+### Seasonal/Flash Sale
+
+Time-limited broad discount:
+- Set `date_expires` to end of sale period
+- Use `minimum_amount` to encourage larger baskets
+- No product restrictions for storewide sales
+
+### Loyalty/VIP Reward
+
+Exclusive codes for returning customers:
+- `email_restrictions`: list specific customer emails
+- `discount_type: "percent"`, higher value (e.g., 25%)
+- `individual_use: true`
+
+## Common Procedures
+
+### Create and Verify Coupon
+
+1. `wc_create_coupon` with full configuration
+2. `wc_get_coupon` with returned ID to confirm all fields saved correctly
+3. Note the `usage_count` field — starts at 0
+
+### Audit Active Coupons
+
+1. `wc_list_coupons` with `per_page: 100`
+2. Check `usage_count` vs `usage_limit` for each
+3. Check `date_expires` to identify expired coupons
+4. `wc_delete_coupon` for expired or exhausted coupons
+
+## Tips and Gotchas
+
+- **Code case**: WooCommerce stores coupon codes in lowercase. `WELCOME20` and `welcome20` are the same code.
+- **Individual use**: `individual_use: true` prevents the coupon from being combined with other coupons in the same cart.
+- **Free shipping**: Set `free_shipping: true` on a coupon to grant free shipping regardless of zone settings — no need to configure a separate free shipping method.
+- **Usage limit vs per-user**: `usage_limit` is the total times the coupon can be used across all customers; `usage_limit_per_user` limits per individual customer account.
+- **Deletion is permanent**: `wc_delete_coupon` does not move to trash. Prefer expiring coupons by setting `date_expires` rather than deleting for audit trail purposes.

package/skills/wp-woocommerce/references/order-workflow.md

@@ -0,0 +1,88 @@
+# Order Workflow
+
+WooCommerce orders follow a defined lifecycle from initial placement through fulfillment or cancellation. Understanding valid status transitions, order notes, and refund processes is essential for efficient store operations.
+
+## MCP Tools
+
+| Tool | Usage |
+|------|-------|
+| `wc_list_orders` | List/filter orders by status, date, customer, or product |
+| `wc_get_order` | Get full order details including line items, billing, shipping |
+| `wc_update_order_status` | Transition order to a new status |
+| `wc_list_order_notes` | List all notes (internal and customer-visible) on an order |
+| `wc_create_order_note` | Add a note to an order |
+| `wc_create_refund` | Create a partial or full refund for an order |
+
+## Order Status Lifecycle
+
+```
+pending → processing → completed
+    ↓          ↓
+ cancelled   on-hold
+              ↓
+           refunded
+              ↓
+            failed
+```
+
+| Status | Meaning |
+|--------|---------|
+| `pending` | Payment not yet received |
+| `processing` | Payment received, awaiting fulfillment |
+| `on-hold` | Awaiting payment confirmation (bank transfer) |
+| `completed` | Order fulfilled and shipped |
+| `cancelled` | Cancelled by customer or admin |
+| `refunded` | Fully refunded |
+| `failed` | Payment failed or declined |
+
+## Valid Status Transitions
+
+- `pending` → `processing`, `on-hold`, `cancelled`, `failed`
+- `processing` → `completed`, `on-hold`, `cancelled`, `refunded`
+- `on-hold` → `processing`, `cancelled`
+- `completed` → `refunded` (via `wc_create_refund`)
+- Any status → `cancelled` (with care — triggers stock restore)
+
+## Filtering Orders
+
+```json
+// Recent processing orders
+{ "status": "processing", "per_page": 50, "orderby": "date", "order": "desc" }
+
+// Orders by date range
+{ "after": "2026-01-01T00:00:00", "before": "2026-01-31T23:59:59" }
+
+// Orders for specific customer
+{ "customer": 42 }
+```
+
+## Order Notes
+
+Two types of notes via `wc_create_order_note`:
+
+- **Customer-visible** (`customer_note: true`): Sent to customer by email; use for shipping updates and tracking numbers.
+- **Internal** (`customer_note: false`): Only visible in WP admin; use for staff notes and pick/pack instructions.
+
+## Refund Process
+
+1. Get order details: `wc_get_order` — verify items, amounts, payment method
+2. Confirm with user: total to refund, which line items, whether to restock
+3. Create refund: `wc_create_refund` with `amount`, `reason`, and optionally `line_items` for partial refunds
+4. Verify: status transitions to `refunded` (full) or stays `processing` (partial)
+
+Partial refund example:
+```json
+{
+  "amount": "15.00",
+  "reason": "Damaged item — partial refund",
+  "restock_items": true
+}
+```
+
+## Tips and Gotchas
+
+- **Restock on cancel**: WooCommerce automatically restocks items when an order is cancelled if stock management is enabled.
+- **Payment gateway refunds**: `wc_create_refund` triggers automatic refund via the payment gateway only if the gateway supports it (Stripe does, PayPal Standard does not).
+- **Cannot un-complete**: Moving from `completed` back to `processing` is not a standard WooCommerce transition — avoid this.
+- **Bulk status updates**: Iterate over order IDs with `wc_update_order_status`; there is no bulk endpoint in `wc/v3`.
+- **Note emails**: Customer-visible notes trigger an email notification to the customer — use sparingly and with care.

package/skills/wp-woocommerce/references/payment-gateways.md

@@ -0,0 +1,69 @@
+# Payment Gateways
+
+WooCommerce supports multiple payment gateways, each configurable for test and live modes. The REST API provides visibility into active gateways, their status, and settings — essential for store health checks and go-live verification.
+
+## MCP Tools
+
+| Tool | Usage |
+|------|-------|
+| `wc_list_payment_gateways` | List all installed gateways with enabled status and settings |
+
+Note: Enabling/disabling gateways and updating API keys requires WooCommerce admin UI. Use `wc_list_payment_gateways` to audit current configuration.
+
+## Built-in Payment Gateways
+
+| Gateway | ID | Notes |
+|---------|----|-------|
+| Direct Bank Transfer | `bacs` | Manual payment; admin must confirm receipt |
+| Check Payments | `cheque` | Manual; slow reconciliation |
+| Cash on Delivery | `cod` | Offline payment at delivery |
+| PayPal Standard | `paypal` | Redirect to PayPal; no SCA/3DS |
+| PayPal Payments | `ppcp-gateway` | Modern PayPal with card fields |
+
+## Popular Extension Gateways
+
+| Gateway | Notes |
+|---------|-------|
+| Stripe | Cards, Apple/Google Pay, SEPA, iDEAL |
+| Square | In-person + online; syncs inventory |
+| Mollie | European-focused; iDEAL, Bancontact, Klarna |
+| Authorize.Net | US-focused; recurring billing |
+| Braintree | PayPal-owned; strong subscription support |
+
+## Gateway Configuration Fields
+
+`wc_list_payment_gateways` returns per gateway:
+
+| Field | Meaning |
+|-------|---------|
+| `enabled` | Whether the gateway is active for checkout |
+| `title` | Customer-facing name at checkout |
+| `description` | Customer-facing description |
+| `settings.testmode` | `yes` = sandbox mode active |
+| `settings.api_key` | Public API key (never log secret keys) |
+
+## Test Mode Workflow
+
+1. `wc_list_payment_gateways` — identify the target gateway, note current `testmode` value
+2. In WooCommerce admin: enable test mode, enter sandbox credentials
+3. Place test orders using gateway's sandbox card numbers
+4. Verify order status transitions correctly (pending → processing → completed)
+5. In WooCommerce admin: disable test mode, enter live credentials
+6. `wc_list_payment_gateways` — confirm `testmode.value` is `"no"` and `enabled` is `true`
+
+## Go-Live Checklist
+
+- `wc_list_payment_gateways` — verify only intended gateways are enabled
+- Confirm `testmode` is `"no"` on all live gateways
+- Confirm SSL is active (`wc_get_system_status` — check `environment.https`)
+- Place a real low-value test transaction and refund it
+- Confirm webhook URLs are registered in gateway dashboard (Stripe, PayPal)
+
+## Tips and Gotchas
+
+- **Never log secret keys**: `wc_list_payment_gateways` may return API settings — filter or redact secret/private keys from any output shared with users.
+- **Test mode and live orders**: If test mode is accidentally left enabled, real customers receive payment errors or test confirmations. Always verify before go-live.
+- **Gateway conflicts**: Some gateways conflict with others (e.g., two Stripe plugins). `wc_get_system_status` active plugin list helps diagnose this.
+- **SCA/3DS compliance**: PayPal Standard does not support Strong Customer Authentication. For EU stores, use PayPal Payments (ppcp-gateway) or Stripe.
+- **COD and digital products**: Cash on Delivery should typically be disabled for downloadable/virtual products. Configure gateway availability in WooCommerce admin.
+- **Currency**: Each gateway supports specific currencies. `wc_list_payment_gateways` settings may include `supported_currencies` — verify store currency compatibility.

package/skills/wp-woocommerce/references/product-management.md

@@ -0,0 +1,61 @@
+# Product Management
+
+WooCommerce product management covers the full lifecycle of items in your store catalog: creation, pricing, inventory, categorization, and publishing. Products can be simple, variable, grouped, or external/affiliate types, each with distinct configuration requirements.
+
+## MCP Tools
+
+| Tool | Usage |
+|------|-------|
+| `wc_list_products` | List/search products with filters (status, category, stock, SKU) |
+| `wc_get_product` | Get full details for a single product by ID |
+| `wc_create_product` | Create a new product (simple or variable parent) |
+| `wc_update_product` | Update pricing, stock, status, description, categories |
+| `wc_delete_product` | Permanently delete a product (irreversible) |
+| `wc_list_product_categories` | List all product categories with hierarchy |
+| `wc_list_product_variations` | List variations of a variable product |
+
+## Product Types
+
+- **Simple** — Single SKU, one price, no variations
+- **Variable** — Multiple variations (size, color) each with own SKU and price
+- **Grouped** — Collection of related simple products displayed together
+- **External/Affiliate** — Product listed on site but purchased externally
+
+## CRUD Workflow: Simple Product
+
+1. Check existing categories: `wc_list_product_categories`
+2. Create product: `wc_create_product` with `name`, `type: "simple"`, `regular_price`, `description`, `categories`, `status: "publish"`
+3. Set stock: include `manage_stock: true`, `stock_quantity`, `stock_status` in create payload
+4. Verify: `wc_get_product` with the returned ID
+
+## CRUD Workflow: Variable Product
+
+1. Create parent product: `wc_create_product` with `type: "variable"`, add `attributes` array (e.g., `[{name: "Size", options: ["S","M","L"], variation: true}]`)
+2. List variations: `wc_list_product_variations` with parent product ID
+3. Update each variation: `wc_update_product` on variation ID to set `regular_price`, `sku`, `stock_quantity`
+4. Publish parent: `wc_update_product` with `status: "publish"`
+
+## Bulk Operations
+
+- **List with filters**: `wc_list_products` supports `per_page` (max 100), `page`, `status`, `category`, `stock_status`, `sku`, `search`
+- **Batch stock update**: iterate over product IDs calling `wc_update_product` per product
+- **Draft then publish**: create products with `status: "draft"`, review, then `wc_update_product` to set `status: "publish"`
+
+## Image Management
+
+Images are set via the `images` array on `wc_create_product` or `wc_update_product`:
+
+```json
+"images": [{"src": "https://example.com/image.jpg", "name": "Product Image", "alt": "Alt text"}]
+```
+
+Use `upload_media` (WP REST Bridge) first to upload to the WordPress media library, then reference the returned URL in the product images array.
+
+## Tips and Gotchas
+
+- **Sale price**: Set both `regular_price` and `sale_price` to activate a sale; omit `sale_price` or set to `""` to end it.
+- **SKU uniqueness**: SKUs must be unique across all products. WooCommerce rejects duplicate SKUs.
+- **Variable products**: The parent product itself has no price — price is set on each variation.
+- **Categories must exist**: `wc_create_product` references category IDs; create categories via WP admin first.
+- **Stock status**: Even with `manage_stock: false`, set `stock_status: "instock"` to make the product purchasable.
+- **Delete is permanent**: `wc_delete_product` bypasses trash. Always confirm with user before deleting.

package/skills/wp-woocommerce/references/shipping-setup.md

@@ -0,0 +1,79 @@
+# Shipping Setup
+
+WooCommerce shipping is organized into zones (geographical regions) with one or more shipping methods per zone. Shipping classes allow different rates for different product types within the same zone. The REST API provides read access to zones and methods for inspection and reporting.
+
+## MCP Tools
+
+| Tool | Usage |
+|------|-------|
+| `wc_list_shipping_zones` | List all configured shipping zones with methods |
+
+Note: Shipping configuration (creating zones, adding methods, setting rates) requires WooCommerce admin UI or direct REST API calls beyond the current tool set. Use `wc_list_shipping_zones` to inspect and document existing configuration.
+
+## Shipping Architecture
+
+```
+Shipping Zone (e.g., "Europe")
+  ├── Regions: countries/states/postcodes
+  └── Methods:
+        ├── Flat Rate ($5.99)
+        ├── Free Shipping (orders > $75)
+        └── Local Pickup
+```
+
+## Shipping Zones
+
+Each zone defines:
+- **Regions**: Countries, states, or postcode ranges covered
+- **Methods**: Available shipping options for customers in those regions
+- **Priority**: Zones are evaluated in order; first matching zone wins
+
+A special **"Rest of the World"** zone (ID: 0) catches all locations not covered by other zones.
+
+## Shipping Methods
+
+| Method | Configuration |
+|--------|---------------|
+| Flat Rate | Fixed fee per order or per item; can vary by shipping class |
+| Free Shipping | Triggered by minimum order amount, coupon, or always free |
+| Local Pickup | In-store collection; optionally charge a handling fee |
+| Table Rate (extension) | Complex rules by weight, quantity, destination |
+
+## Shipping Classes
+
+Shipping classes let you charge different flat rates for different product types within the same zone:
+
+- **Example classes**: "Heavy items", "Fragile", "Oversized"
+- Products are assigned to a class in the product editor
+- Flat Rate methods can define per-class costs
+
+## Free Shipping Thresholds
+
+Free shipping can be configured to activate when:
+- Order subtotal reaches a minimum (e.g., $75+)
+- Customer applies a valid free-shipping coupon
+- Both conditions are met (`minimum_amount` AND coupon)
+
+## Common Inspection Procedure
+
+### Audit Current Shipping Configuration
+
+1. `wc_list_shipping_zones` — list all zones
+2. Review each zone's regions and methods from the response
+3. Identify gaps: regions with no zone coverage, zones with no methods, or disabled methods
+4. Document findings and recommend corrections via WooCommerce admin
+
+### Verify Free Shipping Availability
+
+1. `wc_list_shipping_zones` — find zones with free shipping methods
+2. Check `settings` on the free shipping method for the minimum amount condition
+3. Cross-reference with any coupon that grants `free_shipping: true`
+
+## Tips and Gotchas
+
+- **Zone order matters**: WooCommerce evaluates zones top to bottom. Place more specific zones (e.g., a specific country) above broader ones (e.g., the continent).
+- **Default zone**: If no zone matches a customer's address, no shipping methods are shown and checkout is blocked. Always configure a "Rest of the World" zone.
+- **Shipping class costs**: Flat rate costs can include PHP calculations referencing `[qty]` and `[fee]` placeholders — document these carefully.
+- **Free shipping with coupon**: A coupon with `free_shipping: true` overrides all method costs for the matching zone, not just "Free Shipping" methods.
+- **Local pickup and tax**: Tax on local pickup orders may differ by jurisdiction — verify WooCommerce tax settings when local pickup is enabled.
+- **REST API scope**: The `wc/v3` shipping endpoints are read-only in the current tool set; use WooCommerce admin for configuration changes.

package/skills/wp-woocommerce/references/tax-configuration.md

@@ -0,0 +1,91 @@
+# Tax Configuration
+
+WooCommerce tax configuration defines how tax is calculated, displayed, and applied across different products and customer locations. Correct tax setup is critical for legal compliance, particularly for stores selling across multiple jurisdictions.
+
+## MCP Tools
+
+| Tool | Usage |
+|------|-------|
+| `wc_get_tax_classes` | List all defined tax classes |
+
+Note: Creating tax rates and modifying tax settings requires WooCommerce admin UI or direct REST API calls beyond the current tool set. Use `wc_get_tax_classes` to inspect existing classes.
+
+## Tax Classes
+
+WooCommerce has three built-in tax classes plus custom classes:
+
+| Class | Slug | Typical Use |
+|-------|------|-------------|
+| Standard | (default) | Most physical goods |
+| Reduced Rate | `reduced-rate` | Food, books (EU reduced VAT) |
+| Zero Rate | `zero-rate` | Children's clothing, exports |
+| Custom | user-defined | Country-specific requirements |
+
+Products are assigned to a tax class. If no class is set, the Standard rate applies.
+
+## Tax Rates Structure
+
+Each tax rate is defined by:
+
+| Field | Description |
+|-------|-------------|
+| Country | ISO 3166-1 alpha-2 country code (e.g., `IT`, `DE`, `US`) |
+| State | State/province code or `*` for all |
+| Postcode | Specific postcode range or `*` for all |
+| City | Specific city or `*` for all |
+| Rate | Percentage (e.g., `22.0000` for 22% Italian VAT) |
+| Name | Label shown to customer (e.g., "VAT") |
+| Priority | When multiple rates match, higher priority wins |
+| Compound | Whether this rate is applied on top of other taxes |
+| Shipping | Whether this rate applies to shipping charges |
+
+## Tax Display Options
+
+WooCommerce admin > Settings > Tax:
+
+| Setting | Options |
+|---------|---------|
+| Prices entered with tax | Yes (inclusive) or No (exclusive) |
+| Display prices in shop | Including tax / Excluding tax / Both |
+| Display prices in cart | Including tax / Excluding tax / Both |
+| Price display suffix | e.g., "incl. VAT", "excl. tax" |
+
+## Common Tax Procedures
+
+### Inspect Current Tax Classes
+
+1. `wc_get_tax_classes` — list all classes
+2. Review which classes exist and their slugs
+3. Cross-reference with products to identify class assignments
+
+### EU VAT Setup (example: Italy)
+
+1. In WooCommerce admin, Tax > Standard Rates: add `IT`, `*`, `*`, `*`, `22`, "IVA", priority 1
+2. Reduced Rate tab: add `IT`, rate `10`, for eligible goods
+3. Zero Rate tab: add `IT`, rate `0`, for exempt goods
+4. Enable "Prices entered with tax: Yes" for B2C stores
+
+### US Sales Tax
+
+1. Add state-level rates for each nexus state (e.g., `US`, `CA`, `*`, `*`, `10.25`, "CA Tax")
+2. Consider automated services (see below) for multi-state compliance
+
+## Automated Tax Services
+
+For stores with complex multi-jurisdiction requirements:
+
+| Service | WooCommerce Integration |
+|---------|------------------------|
+| WooCommerce Tax (TaxJar-powered) | Free with WC account; US-focused |
+| TaxJar | Extension; US + Canada + EU |
+| Avalara AvaTax | Enterprise; global coverage |
+| Quaderno | EU VAT + global digital taxes |
+
+## Tips and Gotchas
+
+- **Tax-inclusive pricing**: If prices are entered tax-inclusive, WooCommerce back-calculates the tax component. Switching this setting after products are created can cause price discrepancies.
+- **Customer location**: WooCommerce calculates tax based on the customer's shipping address (or billing address if shipping is disabled). Ensure address collection is enabled.
+- **Digital goods (EU VAT MOSS)**: Digital products sold to EU consumers must use the customer's country VAT rate. Use the WooCommerce EU VAT extension for compliance.
+- **B2B exemptions**: Businesses with valid VAT IDs may be exempt. The EU VAT extension handles VAT number validation.
+- **Tax rounding**: WooCommerce rounds tax per line item by default. For high-volume stores, "Round tax at subtotal level" (in advanced tax settings) may reduce rounding errors.
+- **Test before go-live**: Place test orders from different locations and verify tax amounts before launching to customers.