Add a wallet item

POST/v1/test/members/{id}/wallet

Puts a reward in the member's wallet as an available item, without an offer or a tier. Use it to test the wallet screen and wallet redemptions at checkout. A reward.issued webhook fires.

Permissions: Sandbox secret key.

Guide

Sandbox

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

Request body#

reward_idstring (uuid)Required
The reward to add.

Response fields#

Returns 201 with WalletItem

idstring (uuid)
Send this as wallet_item_id on previews and redemptions.
rewardReward
The reward, in the same shape as the catalog, with kind: "wallet" and no points_cost. Its rules apply at checkout.
Show attributesReward
- idstring (uuid)
  Send this as reward_id on previews and redemptions.
- namestring
  For example Free drip coffee.
- descriptionstring
  Short text for the guest.
- image_urlstring (uri)Nullable
  HTTPS image URL.
- kindstring
  points (catalog) or wallet (given to one member). May grow.
  One of points, wallet
- points_costinteger
  Points the reward costs. Only on points rewards; wallet rewards don't have it.
- discountDiscount
  Show attributesDiscount
  - typestring
    One of amount, percent, free_item, bogo
  - amount_centsinteger
    For amount.
  - percentnumber
    For percent.
  - itemsarray of object
    Item scope, by Square variation id.
    Show attributesHide attributes
    pos_item_idstring
    namestring
  - categoriesarray of object
    Category scope.
    Show attributesHide attributes
    pos_category_idstring
    namestring
  - max_itemsinteger
- rulesRules
  Show attributesRules
  - min_subtotal_centsinteger
    Integer cents.
    Min 0
  - channelsarray of string
    One of app, web
  - location_idsarray of string (uuid)
  - fulfillmentarray of string
    One of pickup, delivery, curbside, dine_in
  - available_timesarray of AvailableTime
    Show attributesAvailableTime
    daysarray of string
    Show valuesHide values
    mon
    tue
    wed
    thu
    fri
    sat
    sun
    startstring
    Local time, HH:MM.
    endstring
    Local time, HH:MM.
  - tier_idsarray of string (uuid)
- starts_atstring (date-time)Nullable
  When the reward becomes available. null means it already is.
- ends_atstring (date-time)Nullable
  When it stops being available. null means no end date.
sourcestring
How the member got it. See the table below. May grow.
One of tier, offer, challenge, journey, support, birthday
offer_idstring (uuid)Nullable
The offer, when source is offer.
statusstring
available, reserved, used or expired.
One of available, reserved, used, expired
issued_atstring (date-time)
When it landed in the wallet.
expires_atstring (date-time)Nullable
After this time it can't be used. null means it doesn't expire.
used_atstring (date-time)Nullable
When an order used it.
order_idstring (uuid)Nullable
The order that used it.

POST/v1/test/members/{id}/wallet

1
2
3
4curl -X POST $UNPLUG_API/test/members/3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40/wallet \
  -H "Authorization: Bearer $UNPLUG_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reward_id": "d4c2e8a6-7b3f-4e1d-9a5c-1f8b6d3e0a92" }'

1
2
3
4
5
6
7
8
9const response = await fetch(`${process.env.UNPLUG_API}/test/members/3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40/wallet`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UNPLUG_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ reward_id: "d4c2e8a6-7b3f-4e1d-9a5c-1f8b6d3e0a92" }),
});
const data = await response.json();

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

response = requests.post(
    f"{os.environ['UNPLUG_API']}/test/members/3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40/wallet",
    headers={
        "Authorization": f"Bearer {os.environ['UNPLUG_KEY']}",
    },
    json={"reward_id": "d4c2e8a6-7b3f-4e1d-9a5c-1f8b6d3e0a92"},
)
data = response.json()

Response JSON201

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{
  "id": "0d6b3e8f-2a7c-4f19-b4e5-9c1a6d2f8b73",
  "reward": {
    "id": "d4c2e8a6-7b3f-4e1d-9a5c-1f8b6d3e0a92",
    "name": "Fall pastry on us",
    "description": "Any pastry, one per order.",
    "image_url": "https://cdn.unplugdining.com/rewards/d4c2e8a6.jpg",
    "kind": "wallet",
    "discount": {
      "type": "free_item",
      "categories": [ { "pos_category_id": "P9MT2XQ6KZR4WLN8HCB3J7VD", "name": "Pastries" } ],
      "max_items": 1
    },
    "rules": { "min_subtotal_cents": 0, "channels": ["app", "web"], "location_ids": [], "fulfillment": [], "available_times": [], "tier_ids": [] },
    "starts_at": null,
    "ends_at": null
  },
  "source": "support",
  "offer_id": null,
  "status": "available",
  "issued_at": "2026-11-05T16:44:30Z",
  "expires_at": null,
  "used_at": null,
  "order_id": null
}

Error descriptions#

404Not found

member_not_found

No member with this id.

404Not found

reward_not_found

No reward with this id.

404Not found

not_found

Called on production.

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#member_not_found",
  "title": "Not found",
  "status": 404,
  "code": "member_not_found",
  "detail": "No member with this id."
}