---
name: woocommerce
description: 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.
version: 1.0.0
auto-load: false
tags: [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.