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

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 oauth_consumer_key, oauth_nonce, oauth_signature, oauth_signature_method=HMAC-SHA1, oauth_timestamp, oauth_version=1.0

Never log or output consumer_key or consumer_secret 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=<source_category_id>&status=publish&per_page=100&page=1
  [&tag=<filter_tag_id>]

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": <cat_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) < 100: break
  page += 1

Maximum per_page is 100 for most endpoints. The X-WP-Total and X-WP-TotalPages response headers report totals. Always read X-WP-TotalPages on the first request to estimate job size.

Session Tracking

Claude MUST emit the following output at each stage. This is mandatory.

STARTUP:

╔══════════════════════════════════════════╗
║  SKILL: woo-category-reorganization      ║
║  STORE: <store_url>                      ║
║  TIME:  <ISO-8601 UTC>                   ║
║  MODE:  <DRY RUN | LIVE>                 ║
╚══════════════════════════════════════════╝

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

[N/TOTAL] <METHOD> <endpoint> → <result_count> records | params: <key>=<val>

COMPLETION (human format):

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

COMPLETION (json format):

{
  "skill": "woo-category-reorganization",
  "store": "<store_url>",
  "completed_at": "<ISO-8601>",
  "records_processed": <n>,
  "output_file": null,
  "dry_run": <bool>
}

Output Format

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

Error Handling

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.