Woo Category Reorganization

woo-category-reorganization

Purpose

Bulk-reassign WooCommerce products to new categories based on filter rules (current category, tag, price range, or meta field value). Useful during catalog restructuring, brand migrations, or seasonal collection reorganizations. Always shows a full preview before executing any changes.

Prerequisites

• WooCommerce store with REST API enabled
• Consumer Key with Read/Write scope
• Minimum WooCommerce version: 3.5.0

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | store_url | string | yes | — | Base URL of the WooCommerce store | | consumer_key | string | yes | — | WooCommerce REST API consumer key (ck_...) | | consumer_secret | string | yes | — | WooCommerce REST API consumer secret (cs_...) | | dry_run | bool | no | true | Preview without executing | | format | string | no | human | Output format: human or json | | source_category_id | int | yes | — | Move products currently in this category | | target_category_id | int | yes | — | Destination category | | mode | string | no | add | add (keep source) or move (remove from source) | | filter_tag_id | int | no | — | Additionally filter by this tag |

Authentication

WooCommerce uses OAuth 1.0a for HTTP and Basic Auth over HTTPS.

For HTTPS stores (recommended):

Authorization: Basic base64(consumer_key:consumer_secret)

For HTTP stores (development only): Use OAuth 1.0a — include oauthconsumerkey, oauthnonce, oauthsignature, oauthsignaturemethod=HMAC-SHA1, oauthtimestamp, oauthversion=1.0

Never log or output consumerkey or consumersecret values.

See docs/AUTHENTICATION.md for full setup instructions.

Safety

Step 3 modifies product category assignments. Always run with dry_run: true first (the default). Verify the product list before moving — this affects storefront navigation and category page SEO.

Workflow Steps

Step 1 — Resolve category names

GET /wp-json/wc/v3/products/categories/{source_category_id}
GET /wp-json/wc/v3/products/categories/{target_category_id}

Step 2 — Fetch products in source category

GET /wp-json/wc/v3/products
  ?category=&status=publish&per_page=100&page=1
  [&tag=]

Extract: id, name, sku, categories

Step 3 — Preview or update

Compute new category list for each product:

• mode: add → append target_category_id, keep source_category_id
• mode: move → replace source_category_id with target_category_id

If dry_run: true: output preview table and stop.

If dry_run: false and confirmed:

PUT /wp-json/wc/v3/products/{id}
  Body: { "categories": [{ "id":  }, ...] }

API Endpoints Used

GET  /wp-json/wc/v3/products/categories    — resolve category names
GET  /wp-json/wc/v3/products               — products in source category
PUT  /wp-json/wc/v3/products/{id}          — update category assignments

Pagination Strategy

WooCommerce REST API uses page/per_page pagination (not cursor-based).

Standard pattern:

page = 1
while True:
  response = GET /endpoint?per_page=100&page=page
  process(response)
  if len(response)                       ║
║  TIME:                     ║
║  MODE:                   ║
╚══════════════════════════════════════════╝

PER-OPERATION (emit after each API call batch):

[N/TOTAL]   →  records | params: =

COMPLETION (human format):

╔══════════════════════════════════════════╗
║  COMPLETE: woo-category-reorganization   ║
║  RECORDS PROCESSED:                   ║
║  OUTPUT: stdout                          ║
╚══════════════════════════════════════════╝

COMPLETION (json format):

{
  "skill": "woo-category-reorganization",
  "store": "",
  "completed_at": "",
  "records_processed": ,
  "output_file": null,
  "dry_run": 
}

Output Format

Human format: table of each product, current categories, and new categories after change.

Error Handling

| Error | Cause | Resolution | |-------|-------|------------| | 401 Unauthorized | Invalid credentials | Verify consumerkey and consumersecret | | 403 Forbidden | Key lacks Read/Write scope | Regenerate with Read/Write scope | | 404 Not Found | Category ID does not exist | Verify category IDs | | 429 Too Many Requests | Rate limit | Wait 2 seconds and retry |

Best Practices

• Always run with dry_run: true first (the default).
• After reorganization, flush WooCommerce transients (WooCommerce → Status → Tools) so category counts update.
• Use mode: add first to verify the target category looks correct before using mode: move.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: navarroido
• Source: navarroido/Woocommerce-skill
• License: MIT

Install and usage instructions live in the source repository linked above.