WooCommerce coupon tool reference
Seven tools for discount coupons. A coupon is money: an amount written here is redeemable at checkout the moment it saves.
The tools
| Tool | Does | Write |
|---|---|---|
wc_get_coupons |
List coupons | |
wc_get_coupon |
Read one coupon | |
wc_get_coupon_count |
Count coupons by status | |
wc_create_coupon |
Create a coupon | Yes |
wc_update_coupon |
Update a coupon | Yes |
wc_delete_coupon |
Trash or delete a coupon | Yes |
wc_empty_coupon_trash |
Purge trashed coupons | Yes |
Requirements
WooCommerce must be active, or none of these tools is registered.
Permissions
| Requires | |
|---|---|
| Scopes, reads | mcp:read, woocommerce:catalog:read |
| Scopes, writes | mcp:write, woocommerce:catalog:write |
| Capability | manage_woocommerce or edit_shop_coupons |
| Write gate | Allow WooCommerce catalog writes |
Two things are worth noticing.
The capability differs from the product tools. Products accept edit_products; coupons accept edit_shop_coupons. A user who can edit products is not automatically able to touch coupons, and the reverse is also true.
The scope does not. Coupons share the woocommerce:catalog:* scopes with products, and the same Allow WooCommerce catalog writes gate. Opening that gate for a price update also opens coupon creation and deletion. There is no way to grant one without the other.
Only six fields are writable
code, description, discount_type, amount, date_expires, usage_limit, plus individual_use and product_ids.
Everything else WooCommerce offers — minimum and maximum spend, per-user usage limits, excluded products and categories, allowed emails, free shipping, exclude-sale-items — cannot be set through MCP. Those fields exist on the coupon and are simply not exposed.
The practical consequence: a coupon created here is less restricted than one created in the admin, because the restrictions that would normally bound it are unreachable. A "10% off" coupon with no minimum spend and no per-user limit is a coupon that can be used on a €5 order, repeatedly, by anyone who finds the code.
Create coupons that need restrictions in the WooCommerce admin, or create them here and add the restrictions there before publicising the code.
The listing hides the expiry date
wc_get_coupons returns id, code, discount_type, amount and usage_limit — and nothing else. date_expires, description, individual_use and product_ids appear only in the single-coupon read.
So you cannot tell from a listing which coupons are still live. Auditing that means one call per coupon.
Deletion, and the two ways to do it
wc_delete_coupon trashes by default and deletes permanently with force. wc_empty_coupon_trash permanently deletes what is already trashed, up to 100 at a time.
Both are marked destructive. Unlike products — which have no deletion tool at all — coupons can be removed entirely through MCP.
Dry runs
Every write supports dry_run, but they are not equally useful:
- Update returns a real
before. Read it. - Create and delete echo back what you sent.
- Empty trash lists the IDs it would purge, which is the one case where the dry run is genuinely informative.
One caveat, covered on its page: wc_delete_coupon's dry run does not check that the coupon exists.
A coupon that already has redemptions
Changing the amount or type of a coupon customers have already used does not alter past orders, but it does change what the same code does next time. If a code is circulating, editing it is a public change to an offer people may have planned around.
Expiring a coupon is usually safer than editing it, and creating a new code is safer than either.