Cancel a redemption

POST/v1/redemptions/{id}/cancel

Releases the hold: held points go back, and a wallet item or unique code is available again. Call it when payment fails, the guest leaves checkout or switches rewards. The app can call it with its member token, so a hold is released even when the guest closes the payment screen before your server hears about it. If you don't cancel, the hold expires by itself after 15 minutes, and until then the guest can't use that reward anywhere else. Below, Maya first chose WELCOME10, then switched to the pastry, so your server cancels the code's hold before creating the new one.

Permissions: Secret key with checkout:write, or a member token for its own member's redemptions.

Guide

Checkout and orders

Request headers#

Idempotency-Keystring
Any string up to 255 characters; use a UUID v4. Kept 24 hours per key (or member) and endpoint. Same key and body replays the first response with Idempotent-Replayed: true.
Max Length 255

Path parameters#

idstring (uuid)Required

Response fields#

Returns 200 with Redemption

idstring (uuid)
Send it in redemption_ids on the order.
statusstring
See Redemption statuses.
One of reserved, captured, canceled, expired, reversed
member_idstring (uuid)Nullable
null for a guest code.
reward_idstring (uuid)Nullable
What was redeemed. One is set.
wallet_item_idstring (uuid)Nullable
What was redeemed. One is set.
codestringNullable
What was redeemed. One is set.
discount_centsinteger
The discount on the cart it was created for.
Min 0
points_costinteger
Points held, then spent on capture. 0 for wallet items and codes.
affected_line_idsarray of string
Cart lines the discount applies to.
order_idstring (uuid)Nullable
The order that captured it.
expires_atstring (date-time)
End of the hold, 15 minutes after creation.
created_atstring (date-time)

POST/v1/redemptions/{id}/cancel

1
2curl -X POST $UNPLUG_API/redemptions/e1d4b7a2-9c3f-4e58-b6a0-2f8d5c1e7b39/cancel \
  -H "Authorization: Bearer $UNPLUG_KEY"

1
2
3
4
5
6
7const response = await fetch(`${process.env.UNPLUG_API}/redemptions/e1d4b7a2-9c3f-4e58-b6a0-2f8d5c1e7b39/cancel`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UNPLUG_KEY}`,
  },
});
const data = await response.json();

1
2
3
4
5
6
7
8
9
10import os
import requests

response = requests.post(
    f"{os.environ['UNPLUG_API']}/redemptions/e1d4b7a2-9c3f-4e58-b6a0-2f8d5c1e7b39/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['UNPLUG_KEY']}",
    },
)
data = response.json()

Response JSON200

1
2
3
4
5
6
7
8
9
10
11
12
13
14{
  "id": "e1d4b7a2-9c3f-4e58-b6a0-2f8d5c1e7b39",
  "status": "canceled",
  "member_id": "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
  "reward_id": null,
  "wallet_item_id": null,
  "code": "WELCOME10",
  "discount_cents": 125,
  "points_cost": 0,
  "affected_line_ids": ["1", "2", "3"],
  "order_id": null,
  "expires_at": "2026-11-05T14:21:15Z",
  "created_at": "2026-11-05T14:06:15Z"
}

Error descriptions#

404Not found

not_found

No redemption with this id in your brand.

409Conflict

redemption_not_reserved

The redemption is already captured, canceled or expired. To undo a captured one, refund the order.

Any endpoint can also return the common errors.

404 Not found

1
2
3
4
5
6
7{
  "type": "https://docs.unplugdining.com/reference/errors#not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No redemption with this id in your brand."
}