Woo Customer Spend Tier Tagger

woo-customer-spend-tier-tagger

Purpose

Segment all customers by their total_spent value into configurable Bronze, Silver, and Gold tiers, then write the tier label as a meta_data field on each customer record. Useful for loyalty programs, email segmentation, and B2C personalization. Includes dry-run preview before any writes.

Prerequisites

• WooCommerce store with REST API enabled (WooCommerce → Settings → Advanced → REST API)
• Consumer Key and Consumer Secret with Read/Write 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 (e.g., https://mystore.com) | | 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 tier assignments without writing to customer records | | format | string | no | human | Output format: human or json | | silver_threshold | number | no | 200 | Minimum totalspent (store currency) for Silver tier | | gold_threshold | number | no | 1000 | Minimum totalspent (store currency) for Gold tier | | meta_key | string | no | _loyalty_tier | The meta_data key to write on each customer | | bronze_label | string | no | Bronze | Label written for Bronze tier customers | | silver_label | string | no | Silver | Label written for Silver tier customers | | gold_label | string | no | Gold | Label written for Gold tier customers | | role | string | no | customer | WordPress user role to filter (use all for all roles) |

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 4 executes customer meta writes. Always run with dry_run: true first (the default) and confirm the tier distribution preview before tagging live. Writing a meta field is non-destructive — re-running the skill updates the tier — but verify the threshold values match your program rules.

Workflow Steps

Step 1 — Fetch all customers

GET /wp-json/wc/v3/customers
  ?role=
  &orderby=registered_date
  &order=asc
  &per_page=100
  &page=1

Extract per customer: id, first_name, last_name, email, total_spent, orders_count Paginate until response length = goldthreshold: tier = goldlabel elif totalspent >= silverthreshold: tier = silverlabel else: tier = bronzelabel

**Step 3 — Preview**

If `dry_run: true`: output tier distribution summary and sample table, then stop.

**Step 4 — Write tier meta**

If `dry_run: false` and user has confirmed:

PUT /wp-json/wc/v3/customers/{id} Body: { "meta_data": [ { "key": "", "value": "" } ] }

Process in batches (sequential PUTs, not batch endpoint — customer batch is not available in WC core). Emit progress after every 50 customers.

## API Endpoints Used

GET /wp-json/wc/v3/customers — list all customers with spend data PUT /wp-json/wc/v3/customers/{id} — write loyalty tier meta field

## 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-spend-tier-tagger║ ║ RECORDS PROCESSED: ║ ║ OUTPUT: ║ ╚══════════════════════════════════════════╝

COMPLETION (json format):

```json
{
  "skill": "woo-customer-spend-tier-tagger",
  "store": "",
  "completed_at": "",
  "records_processed": ,
  "output_file": "",
  "dry_run": 
}

Output Format

Dry-run / preview (human format):

TIER PREVIEW — 1,284 customers (DRY RUN)
Thresholds: Bronze .csv`
Columns: `customer_id`, `email`, `first_name`, `last_name`, `total_spent`, `orders_count`, `tier`, `meta_key`, `meta_value`

## Error Handling

| Error | Cause | Resolution |
|-------|-------|------------|
| `401 Unauthorized` | Invalid or missing credentials | Verify consumer_key and consumer_secret |
| `403 Forbidden` | Consumer Key lacks Read/Write scope | Regenerate key with Read/Write scope |
| `404 Not Found` | Customer ID not found during PUT | Customer may have been deleted; skip and continue |
| `429 Too Many Requests` | Rate limit during sequential PUTs | Wait 2 seconds between batches of 50 |
| `woocommerce_rest_*` error | Validation failure | See `message` in response JSON |

## Best Practices

- Run with `dry_run: true` first (the default). Review the tier distribution before tagging.
- Export the CSV after tagging for use in your email marketing platform.
- Re-run monthly to keep tiers current as customers' spend evolves.
- Use `meta_key` consistently across skills that read loyalty tier data.
- For B2B stores: combine with `woo-b2b-customer-overview` to exclude trade accounts from consumer tiers.

## Source & license

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

- **Author:** [navarroido](https://github.com/navarroido)
- **Source:** [navarroido/Woocommerce-skill](https://github.com/navarroido/Woocommerce-skill)
- **License:** MIT

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