advanced-mcp-plugin/skills/woocommerce.md

name, description, version, auto-load, tags

name	description	version	auto-load	tags
woocommerce	Operations playbook for running a WooCommerce store through this plugin's wc_* tools — products, variations, categories, orders, refunds, coupons, gateways, shipping, tax, reviews, and reporting. Read before any store data task.	1.0.0	false	woocommerce ecommerce products orders store

WooCommerce — Store Operations Playbook

When to use this skill

Load before any task touching store data: catalog, orders, pricing, promotions, settings, or reporting. For how the shop looks, see woodmart-mcp. For strategy and CRO, see ecommerce-consultation.

---

Confirm WooCommerce is live first

Before relying on any wc_* tool, confirm the store is present (wc_get_settings or wc_get_store_stats returning cleanly). The tools are guarded — on a site without WooCommerce they report unsupported rather than erroring. Resolve the target site by its registry id and use only that entry's access method before any mutating call.

---

Catalog

Products

• Read: wc_list_products, wc_get_product.
• Write: wc_create_product, wc_update_product.
• Attributes: wc_get_product_attributes, wc_create_product_attribute, wc_set_product_attributes, wc_get_attribute_terms.

Variations (variable products)

• wc_get_product_variations, wc_get_variation, wc_create_variation, wc_update_variation, wc_delete_variation, wc_batch_update_variations.
• Order of operations: create the parent variable product → define the variation attributes (wc_set_product_attributes with variation: true) → then create variations. Variations without their attribute defined on the parent won't save.

Categories

• wc_list_product_categories, wc_create_product_category.

Reviews

• wc_list_product_reviews — read product reviews (ratings, text, status). Never fabricate reviews; surface the real ones.

---

Orders

• List/read: wc_list_orders, wc_get_order.
• Status transitions: wc_update_order_status (pending → processing → completed, or on-hold/cancelled/refunded). Respect the store's fulfilment flow — don't jump an unpaid order to completed.
• Internal notes: wc_add_order_note (customer-visible or private). Use private notes to log why a manual change was made.
• Refunds: wc_create_refund — this moves money. State the amount and reason, and confirm before issuing unless the user explicitly authorized it. A refund is not easily undone.
• Customers: wc_list_customers, wc_get_customers.

---

Promotions

• Coupons: wc_get_coupons, wc_get_coupon, wc_get_coupon_count, wc_create_coupon, wc_update_coupon, wc_delete_coupon, wc_empty_coupon_trash.
• When creating a coupon, set the guardrails: usage limit, expiry, minimum spend, product/category restriction, and whether it stacks. An uncapped percentage coupon is a liability.

---

Store configuration

• Settings overview: wc_get_settings.
• Payments: wc_list_payment_gateways — which gateways are enabled and in what order (the top enabled gateway is the checkout default).
• Shipping: wc_list_shipping_zones — zones and their methods.
• Tax: wc_list_tax_rates — configured rates by zone/class.

Read these before diagnosing a "customers can't check out" problem — the cause is almost always a disabled gateway, a missing shipping zone for the customer's region, or a tax misconfiguration.

---

Reporting

• wc_sales_report — gross, orders, items sold, currency over a date range. The headline revenue number.
• wc_get_store_stats — broader store snapshot.

Pull the real numbers before making any claim about store performance. For a store with zero recent orders the report returns zeros — report that honestly rather than inferring activity.

---

Safe-change workflow for anything that mutates

1. Read current state (wc_get_* / wc_list_*).
2. Make the minimal change.
3. For money-moving actions (refunds, order completion, uncapped coupons) — confirm intent first; log the reason with wc_add_order_note where it applies.
4. cache_purge_all after catalog/price changes so the storefront reflects them.
5. Verify (re-read, or check the live product/cart).

---

Gotchas

• Price change not showing → catalog cache. cache_purge_all; Woodmart may also cache the product grid.
• Variation won't save → its attribute isn't defined as a variation attribute on the parent.
• Refund issued twice → wc_create_refund is not idempotent. Check wc_get_order for existing refunds before issuing.
• Coupon abused → no usage limit/expiry set. Always cap.
• "Checkout broken" → check gateways, shipping zones, and tax before touching code.
• Reporting looks wrong → confirm the date range and currency; wc_sales_report is period-bound.