woo-product-data-completeness-score

name: woo-product-data-completeness-score role: merchandising description: "Read-only: Score each product against a required fields checklist (images, description, weight, SKU, attributes) and export a completeness gap report." toolkit: woocommerce-rest-api, woocommerce-rest-execution api_version: "wc/v3" rest_endpoints: - GET /products - GET /products/{id} status: stable compatibility: Claude Code, Cursor, Cline, Codex, Gemini CLI

Purpose

Audit every product in your WooCommerce catalog against a configurable completeness checklist and assign a score (0–100). Identifies products missing images, descriptions, weights, SKUs, or other required fields. Exports a prioritized gap report so merchandising teams can systematically improve catalog quality. Read-only — no products are modified.

Prerequisites

WooCommerce store with REST API enabled (WooCommerce → Settings → Advanced → REST API)
Consumer Key and Consumer Secret with Read scope
Store accessible over HTTPS
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	`false`	No effect — read-only skill
`format`	string	no	`human`	Output format: `human` or `json`
`min_images`	int	no	`1`	Minimum image count for a passing score
`min_description_chars`	int	no	`100`	Minimum character count for description field
`require_sku`	bool	no	`true`	Flag products missing SKU
`require_weight`	bool	no	`true`	Flag products missing weight
`require_dimensions`	bool	no	`false`	Flag products missing length/width/height
`score_threshold`	int	no	`80`	Score below which a product is flagged
`category_id`	int	no	—	Limit audit to this category
`status`	string	no	`publish`	Product status to audit

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

Read-only skill — no mutations are executed. Safe to run at any time.

Workflow Steps

Step 1 — Fetch products

GET /wp-json/wc/v3/products
  ?status=<status>&per_page=100&page=1
  [&category=<category_id>]

Extract per product: id, name, sku, description, short_description, images, weight, dimensions, type, categories, tags, attributes Paginate until response length < 100.

Step 2 — Score each product

For each product, compute a completeness score (0–100) by checking:

Has ≥ min_images images → 20 points
description length ≥ min_description_chars → 20 points
short_description is non-empty → 10 points
sku is non-empty (if require_sku) → 20 points
weight is non-empty (if require_weight) → 15 points
dimensions (length/width/height) are non-empty (if require_dimensions) → 10 points
Has ≥ 1 category assigned → 5 points

Flag products with score < score_threshold.

Step 3 — Export report

Sort by score ascending (lowest first). Export CSV.

API Endpoints Used

GET  /wp-json/wc/v3/products           — list all products for audit
GET  /wp-json/wc/v3/products/{id}      — fetch individual product details if needed

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-product-data-completeness-score║
║  STORE: <store_url>                      ║
║  TIME:  <ISO-8601 UTC>                   ║
║  MODE:  READ-ONLY                        ║
╚══════════════════════════════════════════╝

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

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

COMPLETION (human format):

╔══════════════════════════════════════════╗
║  COMPLETE: woo-product-data-completeness ║
║  RECORDS PROCESSED: <n>                  ║
║  OUTPUT: <filename>                      ║
╚══════════════════════════════════════════╝

COMPLETION (json format):

{
  "skill": "woo-product-data-completeness-score",
  "store": "<store_url>",
  "completed_at": "<ISO-8601>",
  "records_processed": <n>,
  "output_file": "<path>",
  "dry_run": false
}

Output Format

CSV filename: woo-product-data-completeness-score_<YYYY-MM-DD>.csv Columns: product_id, sku, name, score, has_images, image_count, has_description, description_chars, has_short_desc, has_sku, has_weight, has_dimensions, category_count, missing_fields

Error Handling

Error	Cause	Resolution
`401 Unauthorized`	Invalid or missing credentials	Verify consumer_key and consumer_secret
`403 Forbidden`	Consumer Key lacks Read scope	Regenerate key with Read scope
`429 Too Many Requests`	Rate limit during pagination	Wait 2 seconds and retry; reduce per_page to 50
Empty result	No products match filters	Check status and category_id parameters

Best Practices

Run after every catalog import to catch products with missing data.
Sort the CSV by score ascending and assign the lowest-scoring products as a weekly cleanup sprint.
Set min_description_chars: 200 for SEO-focused audits (100 chars is below recommended SEO length).
Combine with woo-seo-metadata-audit for a full catalog quality assessment.