wc_empty_coupon_trash: permanently clear trashed coupons

Permanently deletes coupons that are already in the trash. Marked destructive, and genuinely so: nothing survives it.

Arguments

There is no way to select which coupons — it takes everything currently trashed, in batches.

Permissions

Allow WooCommerce catalog writes open, plus manage_woocommerce or edit_shop_coupons.

It handles 100 per call

The tool queries up to 100 trashed coupons and deletes those. A trash containing 250 coupons needs three calls.

The response reports how many were deleted, so a result of exactly 100 is a strong hint there are more:

Purge the trash, then check the coupon count again.

Use wc_get_coupon_count to know the size beforehand and to confirm the trash is empty afterwards.

The dry run is the useful one

Unlike the create and delete dry runs, which echo your arguments, this one returns the actual list of coupon IDs it would purge.

That list is worth reading before every call. It is the last opportunity to notice that something was trashed by accident and is about to become unrecoverable:

Dry-run the purge and show me the IDs, then read each one so I can see the codes.

Note the IDs are all you get — no codes, no amounts. Reading them individually is the only way to see what is about to be destroyed, and after the purge there is nothing to read.

Why you would run it

The reason is usually that a code needs reusing. A trashed coupon keeps its code reserved, so BLACKFRIDAY cannot be recreated while last year's sits in the trash.

Purging frees those codes. That is the intended use, and it is also the risk: an annual code freed by purging is a code with no record of what it did last time.

Nothing here is selective

There is no argument to purge one coupon, or coupons older than a date, or everything except a few. It empties the trash.

If only one code needs freeing, the safer route is to delete that specific coupon permanently with wc_delete_coupon and force, leaving the rest of the trash intact.

Reach for this tool only when clearing the whole trash is genuinely the intent.

Past orders are unaffected

Orders that used these coupons keep their discounts and their totals. What disappears is the coupon record itself, which makes it harder to answer later questions about what a historic code offered.

If that history matters for accounting, export it before purging.

Run it on staging first if the trash is large

A trash of a few coupons is a small decision. A trash of 300 is an archive, and purging it removes the shop's entire record of retired offers.

Confirm with whoever owns the shop's promotions before running it at that scale.

After purging

1. Check the coupon count and confirm trash is zero — or call again if it is not.
2. If you purged to free a code, create the new coupon and confirm the code is accepted.

Common problems

Related

• wc_get_coupon_count — check the size first
• wc_delete_coupon — the selective alternative
• Coupon tools