delete_coupon

Soft-delete a coupon code so nobody can redeem it again. Past redemptions are kept. Refused while a checkout holds the code.

Purpose

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.

Required ability

project-coupon:delete

Input schema

{
  "type": "object",
  "required": ["coupon_id"],
  "properties": {
    "coupon_id": {
      "type": "string",
      "description": "UUID of the coupon to delete."
    }
  }
}

Output shape

{
  "data": {
    "id": "4b9d3e08-a1f6-4275-9c83-7e01d6a2f594",
    "deleted": true
  }
}

id echoes the argument as sent.

Example prompts

"Delete coupon 4b9d3e08-a1f6-4275-9c83-7e01d6a2f594 — the campaign is over."

"Remove the leaked STAFF50 code entirely."

"Get rid of the old Black Friday codes from 2025."

Failure modes

VALIDATION_FAILED — a checkout using the code is still in progress (error.context.coupon carries the refusal and points at deactivating instead), or the caller is a team member whose role lacks the team's coupon-delete permission.
RESOURCE_NOT_FOUND — unknown coupon_id, a coupon on another team's project, one outside the token's scope:project: allow-list, or a coupon already deleted.
AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks project-coupon:delete.

deactivate_coupon — the always-available way to stop a code.
get_coupon — confirm what you are about to delete.
list_coupons
Coupons API — the REST equivalent.
Coupon Codes — the feature walkthrough.