Search and list products in the WooCommerce store catalog.

Supports filtering by search term, SKU, status, type, category, tag, stock status, sale status, and price range. Does NOT return product variations for variable products - use woocommerce_list_product_variations for those.

Args:

• search (string, optional): Match against name/SKU/description

• sku (string, optional): Exact SKU match

• status ('any'|'draft'|'pending'|'private'|'publish'): default 'any'

• type ('simple'|'grouped'|'external'|'variable'): optional

• category (string, optional): category ID(s), comma-separated

• tag (string, optional): tag ID(s), comma-separated

• stock_status ('instock'|'outofstock'|'onbackorder'): optional

• featured (boolean, optional)

• on_sale (boolean, optional)

• min_price / max_price (string, optional): numeric string bounds

• orderby / order: sorting controls

• page / per_page: pagination (default page=1, per_page=20, max 100)

• response_format ('markdown'|'json'): default 'markdown'

Returns: paginated list of products with id, name, sku, type, status, pricing, stock, and categories.

Examples:

• Use when: "find all out of stock products" -> stock_status="outofstock"

• Use when: "show products under $20 on sale" -> on_sale=true, max_price="20.00"

• Don't use when: you need details of one known product ID (use woocommerce_get_product)

Retrieve full details for a single product by ID, including description, pricing, stock, images, categories, tags, attributes, and (for variable products) the list of variation IDs.

Args:

• product_id (number): The product's numeric ID

• response_format ('markdown'|'json'): default 'markdown'

Returns: Full product object.

Error Handling:

• Returns "Error: Resource not found (404)" if the product ID doesn't exist.

Create a new product in the WooCommerce catalog.

Args:

• name (string, required): Product name

• type ('simple'|'grouped'|'external'|'variable'): default 'simple'

• status ('draft'|'pending'|'private'|'publish'): default 'publish'

• description / short_description (string, optional): HTML allowed

• sku (string, optional): must be unique store-wide

• regular_price / sale_price (string, optional): numeric strings

• manage_stock (boolean), stock_quantity (number), stock_status (string)

• category_ids / tag_ids (number[]): assign existing taxonomy terms

• image_urls (string[]): externally hosted image URLs, WooCommerce will import them

• weight (string, optional)

• response_format ('markdown'|'json'): default 'markdown'

Returns: The newly created product object with its assigned ID.

Examples:

• Use when: "add a new t-shirt product priced at $25" -> name="T-Shirt", regular_price="25.00"

• Don't use when: creating a variation of an existing variable product (use woocommerce_create_product_variation)

Error Handling:

• Returns "Error: Bad request (400)" if sku is already in use by another product.

Update fields on an existing product. Only the fields you provide are changed; all other fields are left untouched.

Args:

• product_id (number, required)

• Any subset of: name, status, description, short_description, sku, regular_price, sale_price, manage_stock, stock_quantity, stock_status, category_ids, tag_ids, weight

• response_format ('markdown'|'json'): default 'markdown'

Returns: The updated product object.

Examples:

• Use when: "mark product 42 as out of stock" -> product_id=42, stock_status="outofstock"

• Use when: "put product 42 on sale for $15" -> product_id=42, sale_price="15.00"

Error Handling:

• Returns "Error: Resource not found (404)" if product_id doesn't exist.

Delete a product. By default this moves the product to the trash (recoverable); set force=true to permanently delete it.

Args:

• product_id (number, required)

• force (boolean): permanently delete if true (default: false, moves to trash)

Returns: Confirmation with the deleted product's id, name, and status.

Error Handling:

• Returns "Error: Resource not found (404)" if product_id doesn't exist.

List all variations of a variable product (e.g. a T-shirt with Size/Color variations).

Args:

• product_id (number, required): the parent variable product's ID

• page / per_page: pagination (default page=1, per_page=20, max 100)

• response_format ('markdown'|'json'): default 'markdown'

Returns: paginated list of variations with id, sku, price, stock, and attribute options.

Error Handling:

• Returns an empty list if the product exists but isn't of type 'variable' or has no variations.

Retrieve full details for a single product variation.

Args:

• product_id (number, required): parent product ID

• variation_id (number, required): variation ID

• response_format ('markdown'|'json'): default 'markdown'

Returns: Full variation object including attributes, pricing, and stock.

Error Handling:

• Returns "Error: Resource not found (404)" if either ID is wrong or the variation doesn't belong to that product.

Create a new variation for an existing variable product. The parent product must already have variation-enabled attributes defined (e.g. Size, Color).

Args:

• product_id (number, required): parent variable product ID

• attributes (array, required): [{name, option}] matching the parent's variation attributes

• sku, regular_price, sale_price, manage_stock, stock_quantity, stock_status (optional)

• response_format ('markdown'|'json'): default 'markdown'

Returns: The newly created variation object.

Examples:

• Use when: "add a Large/Blue variation at $30" -> attributes=[{name:"Size",option:"Large"},{name:"Color",option:"Blue"}], regular_price="30.00"

Error Handling:

• Returns "Error: Bad request (400)" if the attribute name/option doesn't match the parent product's defined attributes.

Update fields on an existing product variation (pricing, stock, SKU). Only supplied fields are changed.

Args:

• product_id, variation_id (number, required)

• Any subset of: sku, regular_price, sale_price, manage_stock, stock_quantity, stock_status

• response_format ('markdown'|'json'): default 'markdown'

Returns: The updated variation object.

Error Handling:

• Returns "Error: Resource not found (404)" if the IDs don't match an existing variation.

Permanently delete a product variation.

Args:

• product_id, variation_id (number, required)

• force (boolean, default true): variations do not support trash, so deletion is always permanent

Returns: Confirmation of deletion.

Error Handling:

• Returns "Error: Resource not found (404)" if the IDs don't match an existing variation.

List product categorys defined in the store.

Args:

• search (string, optional): match against name

• parent (number, optional): filter to children of a given category ID

• orderby / order: sorting (default name/asc)

• page / per_page: pagination (default page=1, per_page=20, max 100)

• response_format ('markdown'|'json'): default 'markdown'

Returns: paginated list of categorys with id, name, slug, and product count.

Create a new product category.

Args:

• name (string, required)

• description (string, optional)

• parent (number, optional): parent category ID

• response_format ('markdown'|'json'): default 'markdown'

Returns: The newly created category object with its assigned ID.

Error Handling:

• Returns "Error: Bad request (400)" if a category with this name/slug already exists.

Update fields on an existing product category.

Args:

• id (number, required)

• Any subset of: name, description, parent

• response_format ('markdown'|'json'): default 'markdown'

Returns: The updated category object.

Error Handling:

• Returns "Error: Resource not found (404)" if the ID doesn't exist.

Permanently delete a product category. Products assigned to it are not deleted, just unassigned.

Args:

• id (number, required)

• force (boolean, default true): required to be true, terms do not support trash

Returns: Confirmation of deletion.

Error Handling:

• Returns "Error: Resource not found (404)" if the ID doesn't exist.

List product tags defined in the store.

Args:

• search (string, optional): match against name

• orderby / order: sorting (default name/asc)

• page / per_page: pagination (default page=1, per_page=20, max 100)

• response_format ('markdown'|'json'): default 'markdown'

Returns: paginated list of tags with id, name, slug, and product count.

Create a new product tag.

Args:

• name (string, required)

• description (string, optional)

• response_format ('markdown'|'json'): default 'markdown'

Returns: The newly created tag object with its assigned ID.

Error Handling:

• Returns "Error: Bad request (400)" if a tag with this name/slug already exists.

Update fields on an existing product tag.

Args:

• id (number, required)

• Any subset of: name, description

• response_format ('markdown'|'json'): default 'markdown'

Returns: The updated tag object.

Error Handling:

• Returns "Error: Resource not found (404)" if the ID doesn't exist.

Permanently delete a product tag. Products assigned to it are not deleted, just unassigned.

Args:

• id (number, required)

• force (boolean, default true): required to be true, terms do not support trash

Returns: Confirmation of deletion.

Error Handling:

• Returns "Error: Resource not found (404)" if the ID doesn't exist.

Search and list store orders, with filters for status, customer, date range, and product.

Args:

• status: 'any'|'pending'|'processing'|'on-hold'|'completed'|'cancelled'|'refunded'|'failed'|'trash' (default: any)

• customer (number, optional): customer ID

• search (string, optional)

• after / before (string, optional): ISO8601 dates bounding date_created

• product (number, optional): only orders containing this product ID

• orderby / order: sorting (default date/desc)

• page / per_page: pagination (default page=1, per_page=20, max 100)

• response_format ('markdown'|'json'): default 'markdown'

Returns: paginated list of orders with id, number, status, total, currency, customer, and line item count.

Examples:

• Use when: "show me pending orders from this week" -> status="pending", after="2026-06-29T00:00:00"

• Use when: "how many orders has customer 15 placed" -> customer=15

• Don't use when: you need full line-item and address detail for one order (use woocommerce_get_order)

Retrieve full details for a single order, including line items, billing/shipping addresses, payment info, shipping/fee/coupon lines, and totals.

Args:

• order_id (number, required)

• response_format ('markdown'|'json'): default 'markdown'

Returns: Full order object.

Error Handling:

• Returns "Error: Resource not found (404)" if order_id doesn't exist.

Create a new order with one or more line items. WooCommerce will calculate totals, tax, and stock reduction (for statuses that trigger it) automatically.

Args:

• status: order status (default: pending)

• customer_id (number, optional): omit for a guest order

• payment_method / payment_method_title (string, optional)

• set_paid (boolean, optional): mark as paid immediately

• billing / shipping (object, optional): address fields

• line_items (array, required): [{product_id, variation_id?, quantity}]

• customer_note (string, optional)

• response_format ('markdown'|'json'): default 'markdown'

Returns: The newly created order object with its assigned ID and calculated totals.

Examples:

• Use when: "create an order for 2x product 55 for customer 10" -> customer_id=10, line_items=[{product_id:55, quantity:2}]

Error Handling:

• Returns "Error: Bad request (400)" if a product_id/variation_id doesn't exist or is out of stock with backorders disabled.

Update an existing order's status, addresses, or notes. To change line items, use the WooCommerce admin UI or pass a full 'line_items' array via a direct API call - this tool intentionally keeps line-item edits out of scope to avoid accidental stock/total recalculation mistakes.

Args:

• order_id (number, required)

• status (string, optional): e.g. 'processing', 'completed', 'cancelled', 'refunded'

• customer_note, billing, shipping, set_paid (optional)

• response_format ('markdown'|'json'): default 'markdown'

Returns: The updated order object.

Examples:

• Use when: "mark order 100 as completed" -> order_id=100, status="completed"

Error Handling:

• Returns "Error: Resource not found (404)" if order_id doesn't exist.

Delete an order. By default this moves the order to the trash (recoverable); set force=true to permanently delete it.

Args:

• order_id (number, required)

• force (boolean, default false)

Returns: Confirmation with the deleted order's id, number, and status.

Error Handling:

• Returns "Error: Resource not found (404)" if order_id doesn't exist.

List the internal/customer notes attached to an order (e.g. fulfillment updates, payment gateway logs).

Args:

• order_id (number, required)

• type: 'any'|'customer'|'internal' (default: any)

• response_format ('markdown'|'json'): default 'markdown'

Returns: list of notes with id, author, date, content, and whether it's customer-visible.

Add a note to an order. Customer-visible notes trigger an email to the customer; internal notes are only visible in the admin.

Args:

• order_id (number, required)

• note (string, required)

• customer_note (boolean, default false): true = customer-visible (emails customer), false = internal only

• response_format ('markdown'|'json'): default 'markdown'

Returns: The newly created note object.

Examples:

• Use when: "let the customer know order 100 has shipped" -> order_id=100, note="Your order has shipped!", customer_note=true

List refunds issued against an order.

Args:

• order_id (number, required)

• page / per_page: pagination (default page=1, per_page=20, max 100)

• response_format ('markdown'|'json'): default 'markdown'

Returns: list of refunds with id, amount, reason, and refunded line items.

Issue a refund against an order, either as a flat amount or itemized by line item. This is a DESTRUCTIVE, hard-to-reverse financial operation - confirm details with the user before calling.

Args:

• order_id (number, required)

• amount (string, optional): flat refund amount; required if line_items is omitted

• reason (string, optional)

• line_items (array, optional): [{id, quantity?, refund_total?}] for itemized refunds

• api_refund (boolean, default true): attempt gateway refund vs. record-only

• response_format ('markdown'|'json'): default 'markdown'

Returns: The created refund object.

Examples:

• Use when: "refund $15 of order 100 for a damaged item" -> order_id=100, amount="15.00", reason="Damaged item"

Error Handling:

• Returns "Error: Bad request (400)" if the amount exceeds the order total or the gateway rejects the refund.

Search and list registered customers (does not include guest checkout customers, who aren't stored as customer records).

Args:

• search (string, optional): match against name/email/username

• email (string, optional): exact match

• role (string, optional): WordPress role filter

• orderby / order: sorting (default name/asc)

• page / per_page: pagination (default page=1, per_page=20, max 100)

• response_format ('markdown'|'json'): default 'markdown'

Returns: paginated list of customers with id, email, name, order count, and total spent.

Examples:

• Use when: "find the customer with email jane@example.com" -> email="jane@example.com"

• Don't use when: looking up who placed a guest order (check the order's billing details instead)

Retrieve full details for a single customer, including billing/shipping addresses, order count, and lifetime spend.

Args:

• customer_id (number, required)

• response_format ('markdown'|'json'): default 'markdown'

Returns: Full customer object.

Error Handling:

• Returns "Error: Resource not found (404)" if customer_id doesn't exist.

Create a new registered customer account.

Args:

• email (string, required): must be unique

• first_name / last_name (string, optional)

• username / password (string, optional): auto-generated if omitted

• billing / shipping (object, optional): address fields

• response_format ('markdown'|'json'): default 'markdown'

Returns: The newly created customer object with its assigned ID.

Error Handling:

• Returns "Error: Bad request (400)" if the email or username is already registered.

Update fields on an existing customer. Only supplied fields are changed.

Args:

• customer_id (number, required)

• Any subset of: email, first_name, last_name, billing, shipping

• response_format ('markdown'|'json'): default 'markdown'

Returns: The updated customer object.

Error Handling:

• Returns "Error: Resource not found (404)" if customer_id doesn't exist.

Permanently delete a customer account. Customers don't support trash; this cannot be undone. Existing orders remain but become unlinked from the account.

Args:

• customer_id (number, required)

• reassign (number, optional): user ID to reassign content to

Returns: Confirmation of deletion.

Error Handling:

• Returns "Error: Resource not found (404)" if customer_id doesn't exist.

Search and list discount coupons defined in the store.

Args:

• search (string, optional): match against coupon code

• code (string, optional): exact code match

• orderby / order: sorting (default date/desc)

• page / per_page: pagination (default page=1, per_page=20, max 100)

• response_format ('markdown'|'json'): default 'markdown'

Returns: paginated list of coupons with code, amount, discount type, usage count/limit, and expiry.

Retrieve full details for a single coupon, including restrictions (min/max spend, product/category restrictions, email restrictions).

Args:

• coupon_id (number, required)

• response_format ('markdown'|'json'): default 'markdown'

Returns: Full coupon object.

Error Handling:

• Returns "Error: Resource not found (404)" if coupon_id doesn't exist.

Create a new discount coupon.

Args:

• code (string, required): the code customers enter at checkout

• discount_type: 'percent'|'fixed_cart'|'fixed_product' (default: fixed_cart)

• amount (string, required): numeric string

• description, date_expires (YYYY-MM-DD), individual_use, usage_limit, usage_limit_per_user, free_shipping, minimum_amount, maximum_amount, product_ids, excluded_product_ids, email_restrictions (all optional)

• response_format ('markdown'|'json'): default 'markdown'

Returns: The newly created coupon object with its assigned ID.

Examples:

• Use when: "create a 20% off coupon called SUMMER20 that expires end of August" -> code="SUMMER20", discount_type="percent", amount="20", date_expires="2026-08-31"

Error Handling:

• Returns "Error: Bad request (400)" if the coupon code already exists.

Update fields on an existing coupon. Only supplied fields are changed.

Args:

• coupon_id (number, required)

• Any subset of: code, discount_type, amount, description, date_expires, usage_limit, usage_limit_per_user, free_shipping, minimum_amount, maximum_amount

• response_format ('markdown'|'json'): default 'markdown'

Returns: The updated coupon object.

Examples:

• Use when: "extend coupon 12's expiry to end of year" -> coupon_id=12, date_expires="2026-12-31"

Error Handling:

• Returns "Error: Resource not found (404)" if coupon_id doesn't exist.

Delete a coupon. By default this moves it to the trash (recoverable); set force=true to permanently delete it.

Args:

• coupon_id (number, required)

• force (boolean, default false)

Returns: Confirmation with the deleted coupon's id and code.

Error Handling:

• Returns "Error: Resource not found (404)" if coupon_id doesn't exist.

Retrieve aggregate sales totals (revenue, orders, items, tax, shipping, discounts, refunds) for a period or custom date range.

Args:

• period: 'week'|'month'|'last_month'|'year' (optional; omit if using date_min/date_max)

• date_min / date_max (string, optional): YYYY-MM-DD custom range, overrides 'period'

• response_format ('markdown'|'json'): default 'markdown'

Returns: Sales totals summary. If neither period nor date range is given, WooCommerce defaults to the current week.

Examples:

• Use when: "what were our sales last month" -> period="last_month"

• Use when: "sales between June 1 and June 30" -> date_min="2026-06-01", date_max="2026-06-30"

Retrieve the best-selling products (by quantity sold) for a period or custom date range.

Args:

• period: 'week'|'month'|'last_month'|'year' (optional; omit if using date_min/date_max)

• date_min / date_max (string, optional): YYYY-MM-DD custom range, overrides 'period'

• response_format ('markdown'|'json'): default 'markdown'

Returns: list of products with product_id, title, and quantity sold, ordered by quantity descending. Defaults to the current week if no period/range given.

Examples:

• Use when: "what were our best selling products this year" -> period="year"

Get a breakdown of total counts by status for a resource (e.g. how many orders are in each status, or total product/customer/coupon/review counts).

Args:

• resource: 'orders'|'products'|'customers'|'coupons'|'reviews'

• response_format ('markdown'|'json'): default 'markdown'

Returns: list of {slug, name, total} entries, e.g. for orders: pending/processing/completed/etc counts.

Examples:

• Use when: "how many orders are currently pending vs completed" -> resource="orders"