Woo Customer Note Bulk Annotator

woo-customer-note-bulk-annotator

Purpose

Append a text note to the WooCommerce customer note field (customer_note) for multiple customers matching a filter (role, spend range, country, or registration date). Useful for adding internal flags, account status notes, or support context in bulk. Includes dry-run preview.

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 | | note | string | yes | — | Text to append to each customer's note | | filter_role | string | no | — | WordPress role to filter | | filter_min_spend | number | no | — | Minimum totalspent | | filter_max_spend | number | no | — | Maximum totalspent | | filter_country | string | no | — | Two-letter billing country code | | append_mode | bool | no | true | If true, append to existing note; if false, overwrite |

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 writes to customer records. Always run with dry_run: true first (the default). If append_mode: false, existing customer notes are overwritten.

Workflow Steps

Step 1 — Fetch filtered customers

GET /wp-json/wc/v3/customers?per_page=100&page=1
  [&role=]
  [&country=]

Filter client-side by total_spent range. Extract: id, email, customer_note

Step 2 — Compute new note

If append_mode: true: new_note = existing_note + "\n" + note + " [" + date + "]" If append_mode: false: new_note = note

Step 3 — Preview or execute

If dry_run: true: list customers. Stop.

If dry_run: false and confirmed:

PUT /wp-json/wc/v3/customers/{id}
  Body: { "customer_note": "" }

API Endpoints Used

GET  /wp-json/wc/v3/customers        — filtered customer list
PUT  /wp-json/wc/v3/customers/{id}   — write updated note

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-customer-note-bulk-anno.  ║
║  RECORDS PROCESSED:                   ║
║  OUTPUT: stdout                          ║
╚══════════════════════════════════════════╝

COMPLETION (json format):

{
  "skill": "woo-customer-note-bulk-annotator",
  "store": "",
  "completed_at": "",
  "records_processed": ,
  "output_file": null,
  "dry_run": 
}

Output Format

Human format: count of customers to annotate and the first 10 email addresses.

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 | | 429 Too Many Requests | Rate limit | Wait 2 seconds and retry |

Best Practices

• Always run with dry_run: true first.
• Use append_mode: true (the default) to preserve existing notes.
• Include the date in your note text for a built-in audit trail.

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.