Create a redemption

POST/v1/redemptions

Holds one reward, wallet item or code for this cart while the guest pays. For a points reward the points are held, not yet spent. A wallet item or unique code becomes reserved. The hold lasts 15 minutes; it becomes final when you send the order with this redemption's id.

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

Guide

Checkout and orders

Request headers#

Idempotency-KeystringRequired
Required on this endpoint. Any string up to 255 characters; use a UUID v4. Missing returns 400 idempotency_key_required.
Max Length 255

Request body#

The cart, plus exactly one of:

member_idstring (uuid)
location_idstring (uuid)Required
channelstringRequired
app or web.
One of app, web
fulfillmentstringRequired
One of pickup, delivery, curbside, dine_in
currencystringRequired
ISO 4217 code. USD.
subtotal_centsintegerRequired
Integer cents.
Min 0
itemsarray of CartItemRequired
Show attributesCartItem
- line_idstringRequired
  Your id for the line, unique within the cart.
- pos_item_idstring
  Square catalog item variation id.
- namestringRequired
- quantityintegerRequired
  Min 1
- unit_price_centsintegerRequired
  Integer cents.
  Min 0
- pos_category_idsarray of string
- modifiersarray of object
  Show attributesHide attributes
  - pos_modifier_idstring
  - namestring
  - price_centsinteger
    Integer cents.
    Min 0
reward_idstring (uuid)
A catalog reward bought with points.
wallet_item_idstring (uuid)
An available item from the member's wallet.
codestring
A promo code. Works without member_id for guest checkout.

Create redemptions from your server, as here, so it charges with the confirmed discount_cents. Take it off the price, then charge the card. Once payment is captured, send the order with "redemption_ids": ["4b8d2f6a-9c1e-4a3d-b7f5-0e6c8a2d1b59"].

Warning If payment takes longer than 15 minutes, the hold expires and an order that includes it fails with 422 redemption_expired. Create the redemption right before you charge, not when the guest opens the cart.

Only one redemption can be used per order at launch. Stacking several rewards on one order is Coming soon.

Response fields#

Returns 201 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)

Codes without a member#

For a guest who isn't signed in, leave out member_id and send code. Call it with your secret key, since there is no member token. The rest works the same.

POST/v1/redemptions

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18curl -X POST $UNPLUG_API/redemptions \
  -H "Authorization: Bearer $UNPLUG_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5c9e1a7d-3f2b-4d8e-9a6c-0b4f8d2e7a15" \
  -d '{
    "member_id": "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
    "location_id": "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
    "channel": "app",
    "fulfillment": "pickup",
    "currency": "USD",
    "subtotal_cents": 1250,
    "items": [
      { "line_id": "1", "pos_item_id": "HV4MZ2TQ7LW3KXRB5P8NJ6DC", "name": "Oat latte", "quantity": 1, "unit_price_cents": 575, "pos_category_ids": ["C4RZ8NQ2MXK7WTP3LHB6V5JD"], "modifiers": [] },
      { "line_id": "2", "pos_item_id": "3NZQ7XKJ2Y5PLVKCW6RQ4G2T", "name": "Drip coffee", "quantity": 1, "unit_price_cents": 325, "pos_category_ids": ["C4RZ8NQ2MXK7WTP3LHB6V5JD"], "modifiers": [] },
      { "line_id": "3", "pos_item_id": "7PKD3RXN2WQ6ZLHM4TB5JV8C", "name": "Butter croissant", "quantity": 1, "unit_price_cents": 350, "pos_category_ids": ["P9MT2XQ6KZR4WLN8HCB3J7VD"], "modifiers": [] }
    ],
    "wallet_item_id": "7e3a9c51-0b8d-4f2e-a6c4-5d1b9e7f3a28"
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47const response = await fetch(`${process.env.UNPLUG_API}/redemptions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UNPLUG_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "5c9e1a7d-3f2b-4d8e-9a6c-0b4f8d2e7a15",
  },
  body: JSON.stringify({
    member_id: "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
    location_id: "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
    channel: "app",
    fulfillment: "pickup",
    currency: "USD",
    subtotal_cents: 1250,
    items: [
      {
        line_id: "1",
        pos_item_id: "HV4MZ2TQ7LW3KXRB5P8NJ6DC",
        name: "Oat latte",
        quantity: 1,
        unit_price_cents: 575,
        pos_category_ids: ["C4RZ8NQ2MXK7WTP3LHB6V5JD"],
        modifiers: [],
      },
      {
        line_id: "2",
        pos_item_id: "3NZQ7XKJ2Y5PLVKCW6RQ4G2T",
        name: "Drip coffee",
        quantity: 1,
        unit_price_cents: 325,
        pos_category_ids: ["C4RZ8NQ2MXK7WTP3LHB6V5JD"],
        modifiers: [],
      },
      {
        line_id: "3",
        pos_item_id: "7PKD3RXN2WQ6ZLHM4TB5JV8C",
        name: "Butter croissant",
        quantity: 1,
        unit_price_cents: 350,
        pos_category_ids: ["P9MT2XQ6KZR4WLN8HCB3J7VD"],
        modifiers: [],
      },
    ],
    wallet_item_id: "7e3a9c51-0b8d-4f2e-a6c4-5d1b9e7f3a28",
  }),
});
const data = await response.json();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49import os
import requests

response = requests.post(
    f"{os.environ['UNPLUG_API']}/redemptions",
    headers={
        "Authorization": f"Bearer {os.environ['UNPLUG_KEY']}",
        "Idempotency-Key": "5c9e1a7d-3f2b-4d8e-9a6c-0b4f8d2e7a15",
    },
    json={
        "member_id": "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
        "location_id": "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
        "channel": "app",
        "fulfillment": "pickup",
        "currency": "USD",
        "subtotal_cents": 1250,
        "items": [
            {
                "line_id": "1",
                "pos_item_id": "HV4MZ2TQ7LW3KXRB5P8NJ6DC",
                "name": "Oat latte",
                "quantity": 1,
                "unit_price_cents": 575,
                "pos_category_ids": ["C4RZ8NQ2MXK7WTP3LHB6V5JD"],
                "modifiers": [],
            },
            {
                "line_id": "2",
                "pos_item_id": "3NZQ7XKJ2Y5PLVKCW6RQ4G2T",
                "name": "Drip coffee",
                "quantity": 1,
                "unit_price_cents": 325,
                "pos_category_ids": ["C4RZ8NQ2MXK7WTP3LHB6V5JD"],
                "modifiers": [],
            },
            {
                "line_id": "3",
                "pos_item_id": "7PKD3RXN2WQ6ZLHM4TB5JV8C",
                "name": "Butter croissant",
                "quantity": 1,
                "unit_price_cents": 350,
                "pos_category_ids": ["P9MT2XQ6KZR4WLN8HCB3J7VD"],
                "modifiers": [],
            },
        ],
        "wallet_item_id": "7e3a9c51-0b8d-4f2e-a6c4-5d1b9e7f3a28",
    },
)
data = response.json()

Response JSON201

1
2
3
4
5
6
7
8{
  "id": "4b8d2f6a-9c1e-4a3d-b7f5-0e6c8a2d1b59",
  "status": "reserved",
  "discount_cents": 350,
  "points_cost": 0,
  "affected_line_ids": ["3"],
  "expires_at": "2026-11-05T14:22:02Z"
}

Error descriptions#

400Bad request

idempotency_key_required

The Idempotency-Key header is missing.

400Bad request

invalid_request

None, or more than one, of reward_id, wallet_item_id and code was sent.

404Not found

member_not_found

, 404 location_not_found, 404 reward_not_found An id doesn't exist in your brand.

409Conflict

request_in_progress

A request with this key is still running. Retry after a second.

422Unprocessable

insufficient_points

The member can't afford the reward.

422Unprocessable

reward_not_applicable

The reward or wallet item doesn't apply to this cart. Preview the cart to get the reason code and guest message.

422Unprocessable

reward_expired

The wallet item or reward has expired.

422Unprocessable

reward_already_used

The wallet item or unique code was already used.

422Unprocessable

code_invalid

, 422 code_expired, 422 code_limit_reached The code doesn't exist, has ended, or has been used as many times as allowed.

422Unprocessable

idempotency_key_reused

This key was used with a different body.

Any endpoint can also return the common errors.

400 Bad request

1
2
3
4
5
6
7{
  "type": "https://docs.unplugdining.com/reference/errors#idempotency_key_required",
  "title": "Bad request",
  "status": 400,
  "code": "idempotency_key_required",
  "detail": "The Idempotency-Key header is missing."
}