Skip to content
woo-coupon-hygiene-cleanup logo

Woo Coupon Hygiene Cleanup

woo-coupon-hygiene-cleanup

Find expired, zero-use, or past-expiry coupons and batch-delete after confirmation.

SKILL.md

Full skill instructions

woo-coupon-hygiene-cleanup

Purpose

Audit WooCommerce coupons for expired, never-used, or usage-exhausted codes and delete them in batch after confirmation. Reduces coupon table bloat and prevents confusion from stale codes. Includes dry-run preview listing every coupon to be deleted.

Prerequisites

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

Parameters

ParameterTypeRequiredDefaultDescription
store_urlstringyes—Base URL of the WooCommerce store
consumer_keystringyes—WooCommerce REST API consumer key (ck_...)
consumer_secretstringyes—WooCommerce REST API consumer secret (cs_...)
dry_runboolnotruePreview without deleting
formatstringnohumanOutput format: human or json
delete_expiredboolnotrueDelete coupons past their date_expires
delete_zero_useboolnofalseDelete coupons that have never been used (use with caution)
delete_usage_exhaustedboolnotrueDelete coupons where usage_count >= usage_limit
expired_beforestringno<today>Only delete coupons that expired before this date
force_deleteboolnotruePermanently delete (bypass trash)

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 permanently deletes coupons. Deleted coupons cannot be recovered. Always run with dry_run: true first (the default) and review the list carefully. Do not use delete_zero_use: true without verifying those coupons are not in active email campaigns.

Workflow Steps

Step 1 — Fetch all coupons

GET /​wp-json/​wc/​v3/​coupons?per_page=100&page=1

Extract: id, code, discount_type, amount, date_expires, usage_count, usage_limit, date_created

Step 2 — Classify coupons for deletion

  • Expired: date_expires != null and date_expires < now (and < expired_before)
  • Zero-use: usage_count == 0 (if delete_zero_use: true)
  • Usage exhausted: usage_limit > 0 and usage_count >= usage_limit

Step 3 — Preview or delete

If dry_run: true: list coupons to be deleted. Stop.

If dry_run: false and confirmed:

DELETE /​wp-json/​wc/​v3/​coupons/​{id}?force=<force_delete>

API Endpoints Used

GET     /​wp-json/​wc/​v3/​coupons        — list all coupons
DELETE  /​wp-json/​wc/​v3/​coupons/​{id}   — delete individual coupon

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-coupon-hygiene-cleanup       ║
║  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-coupon-hygiene-cleanup    ║
║  RECORDS PROCESSED: <n>                  ║
║  OUTPUT: stdout                          ║
╚══════════════════════════════════════════╝

COMPLETION (json format):

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

Output Format

Human format: table of coupon codes, expiry date, usage count, and deletion reason.

Error Handling

ErrorCauseResolution
401 UnauthorizedInvalid credentialsVerify consumer_key and consumer_secret
403 ForbiddenKey lacks Read/​Write scopeRegenerate with Read/​Write scope
429 Too Many RequestsRate limit during deleteWait 2 seconds and retry

Best Practices

  • Always run with dry_run: true first (the default). Deletion is permanent.
  • Never enable delete_zero_use: true without cross-referencing active email campaigns using those codes.
  • Run quarterly as routine coupon table maintenance.

More Marketing skills

copywriting logo
Marketing

copywriting

Marketing copy for homepages, landing pages, pricing pages, and other conversion-focused web pages.

53.3K 216.1K
View
flux-2-klein logo
Marketing

flux-2-klein

Fast image generation with Flux 2 Klein, optimized for sub-second iteration and multi-reference brand styling.

52 176.2K
View

Psychological principles and mental models for understanding customer behavior and influencing marketing decisions.

53.3K 153K
View

Plan searchable and shareable content that drives traffic, builds authority, and generates leads.

53.3K 150.9K
View

Build SEO-optimized pages at scale using templates, data, and proven playbook patterns.

53.3K 140.1K
View

Brainstorm and prioritize marketing strategies tailored to your SaaS stage, budget, and goals.

53.3K 137.2K
View
ai-seo logo
Marketing

ai-seo

Optimize content for discovery, citation, and visibility across AI search platforms and LLM assistants.

53.3K 136.7K
View
copy-editing logo
Marketing

copy-editing

Systematic improvement of existing marketing copy through seven focused editing passes.

53.3K 136.4K
View

Plan and optimize your website's page hierarchy, navigation, URL structure, and internal linking.

53.3K 112.8K
View
revops logo
Marketing

revops

Design and optimize systems connecting marketing, sales, and customer success into a unified revenue engine.

53.3K 104.9K
View

Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.

179.7K 100.1K
View

Convert websites into professional HyperFrames videos with guided storyboarding and brand-aligned composition.

57K 93.5K
View

Sales & marketing AI tools

KreadoAI logo
Sales & marketing

KreadoAI

Revolutionize Video Creation with AI-Generated Avatars and Voices

Paid
View
Followr logo
Sales & marketing

Followr

Social media on autopilot

Paid
View
Logodiffusion logo
Sales & marketing

Logodiffusion

Design custom logos instantly with AI.

Paid
View
I
Sales & marketing

Ideogram

Text-heavy marketing and design images

Freemium
View
Prompt Silo logo
Sales & marketing

Prompt Silo

Boost Your SEO with Content and SEO Silos

Free
View
Marketing Blocks logo
Sales & marketing

Marketing Blocks

Revolutionize Your Marketing with AI-Powered MarketingBlocks!

Paid
View
Scrip AI logo
Sales & marketing

Scrip AI

10X faster & free AI content creation for 100+ use cases

Free
View
Tribescaler logo
Sales & marketing

Tribescaler

Tribescaler | Make Your Tweets Go Viral

Paid
View