Management API · Points and member support

Create a points adjustment

POST/v1/members/{id}/points_adjustments

Adds or removes points by hand. Use it for goodwill after a bad order, to fix a mistake, or to bring balances over from a previous program. Don't use it to credit orders: send those to POST /v1/orders so they earn at the right rate and refunds work.

Permissions: Secret key with points:adjust.

Guide

Points and rewards

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

Path parameters#

idstring (uuid)Required
The member id.

Request body#

pointsintegerRequired
Positive to add, negative to remove. Not zero.
reasonstringRequired
goodwill, correction, migration or other.
One of goodwill, correction, migration, other
notestring
Why, for your team. For example Cold latte at South Congress.
counts_toward_tierboolean
Default false. When true, positive points also add to lifetime_points and can move the member up a tier. Use it for migration so guests keep their status.
Default false

Returns the activity entry it created. This is the goodwill adjustment from Maya's history above, made on October 27 when she had 308 Beans:

unPLUG records which secret key made every adjustment. A negative adjustment can't take the balance below zero: removing 500 Beans from Maya now, with 420, fails and nothing changes.

Response fields#

Returns 201 with ActivityEntry

idstring (uuid)
typestring
What happened. See the table below. May grow.
One of earn, bonus, redeem, adjust, reverse, expire
pointsinteger
Signed change: 62 for an earn, -500 for a redeem.
balance_afterinteger
The member's points_balance right after this entry.
descriptionstring
A short line you can show the guest, for example Visit at South Congress or Free drip coffee.
order_idstring (uuid)Nullable
The order that caused it, for earn, bonus, redeem and reverse.
reward_idstring (uuid)Nullable
The reward bought, for redeem.
adjustment_reasonstringNullable
For adjust: goodwill, correction, migration or other.
One of goodwill, correction, migration, other
created_atstring (date-time)

POST/v1/members/{id}/points_adjustments

1
2
3
4
5
6
7
8
9curl -X POST $UNPLUG_API/members/3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40/points_adjustments \
  -H "Authorization: Bearer $UNPLUG_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6b3f1d8e-4a2c-4e7b-9d05-8c1a3f6e2b94" \
  -d '{
    "points": 50,
    "reason": "goodwill",
    "note": "Cold latte at South Congress"
  }'

1
2
3
4
5
6
7
8
9
10const response = await fetch(`${process.env.UNPLUG_API}/members/3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40/points_adjustments`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UNPLUG_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "6b3f1d8e-4a2c-4e7b-9d05-8c1a3f6e2b94",
  },
  body: JSON.stringify({ points: 50, reason: "goodwill", note: "Cold latte at South Congress" }),
});
const data = await response.json();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import os
import requests

response = requests.post(
    f"{os.environ['UNPLUG_API']}/members/3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40/points_adjustments",
    headers={
        "Authorization": f"Bearer {os.environ['UNPLUG_KEY']}",
        "Idempotency-Key": "6b3f1d8e-4a2c-4e7b-9d05-8c1a3f6e2b94",
    },
    json={
        "points": 50,
        "reason": "goodwill",
        "note": "Cold latte at South Congress",
    },
)
data = response.json()

Response JSON201

1
2
3
4
5
6
7
8
9
10
11{
  "id": "f7a3c9e2-4d1b-4b6f-9e8a-2c0d5f7b1e43",
  "type": "adjust",
  "points": 50,
  "balance_after": 358,
  "description": "Courtesy points",
  "order_id": null,
  "reward_id": null,
  "adjustment_reason": "goodwill",
  "created_at": "2026-10-27T13:05:18Z"
}

Error descriptions#

400Bad request

idempotency_key_required

The Idempotency-Key header is missing.

400Bad request

invalid_param

points is zero or not an integer, or reason isn't one of the four values.

404Not found

member_not_found

No member with this id.

410Gone

member_deleted

The member was deleted.

422Unprocessable

insufficient_points

A negative adjustment is larger than the balance.

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."
}