delete_coupon
Soft-delete a coupon code so nobody can redeem it again. Past redemptions are kept. Refused while a checkout holds the code.
Retire a coupon code permanently. The row is soft-deleted: the code disappears from every list and
can never be redeemed again, while the redemptions already recorded and the discounts already
applied stay in the history. Emits coupon.deleted with a
snapshot taken before the row goes, because a consumer reacting to a deletion has no way left to
look the coupon up.
Confirm the target with a human
Deletion cannot be undone from the API. The tool is annotated destructive so a
client can prompt for confirmation; read the code back with
get_coupon and confirm the coupon_id before
calling.
Refused while a checkout is using the code
If a buyer has applied the code and their checkout has not settled, the
discount has already been quoted to a gateway. The service refuses with
VALIDATION_FAILED rather than pull the code out from under them. Call
deactivate_coupon instead: it stops new
redemptions at once and never refuses for a checkout in flight. Delete later,
once the hold has cleared.
Idempotent: a second call on the same id finds nothing and answers RESOURCE_NOT_FOUND, exactly as
an unknown or out-of-scope id does.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Annotations
A client that honours annotations asks a person before running it. Sending the same arguments twice changes nothing the second time.
Arguments
coupon_id*stringUUID of the coupon to delete.
What it returns
{ "data": { "id": "4b9d3e08-a1f6-4275-9c83-7e01d6a2f594", "deleted": true }}id echoes the argument as sent.
How it fails
VALIDATION_FAILEDa checkout using the code is still in progress (error.context.coupon
RESOURCE_NOT_FOUNDunknown coupon_id, a coupon on another team's project, one outside the
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks project-coupon:delete.
How is this guide?
Last updated on