Create a refund

POST/v1/orders/{id}/refunds

Records a refund you already made to the guest's card, so unPLUG takes back the points the refunded part earned. Send one call per refund, partial or full.

Permissions: Secret key with checkout:write.

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

Path parameters#

idstring (uuid)Required

Request body#

external_refund_idstringRequired
Your refund id.
amount_centsinteger
For a partial refund: the part of the subtotal after discounts that you refunded. Leave out tax and tip. Send this or full.
Min 1
fullboolean
true to refund everything not yet refunded.
reasonstring
Your reason, for example requested_by_customer.

Response fields#

Returns 201 with Refund

idstring (uuid)
order_idstring (uuid)
external_refund_idstring
Your refund id.
amount_centsinteger
The part of the subtotal after discounts that was refunded. For a full refund, everything not refunded before.
Min 0
fullboolean
true for a full refund.
reasonstringNullable
As you sent it.
points_reversedinteger
Earned points taken back.
points_shortfallinteger
Points that couldn't be taken back because the member had already spent them. The balance stops at zero.
order_statusstring
The order's status after this refund: partially_refunded or refunded.
One of partially_refunded, refunded
member_idstring (uuid)Nullable
The order's member. null for a guest order.
memberobjectNullable
{ "points_balance" } after the refund. null for a guest order.
Show attributesHide attributes
- points_balanceinteger
created_atstring (date-time)

What a refund does#

Earned points are reversed in proportion: points_earned × amount_cents ÷ the order's subtotal after discounts, rounded down. The member gets a reverse activity entry.
Partial refunds keep the redemption captured. The guest keeps the reward.
A full refund also reverses the redemption: points spent on a points reward come back, and a wallet item or unique code returns to the member if it hasn't expired.
The balance never goes below zero. If the member already spent the points, the part that can't be taken back is reported in points_shortfall.

Maya's latte was made with the wrong milk, and you refund $5.00:

The order earned 90 Beans on $9.00, so $5.00 reverses 90 × 500 ÷ 900 = 50 Beans. Maya goes from 510 to 460. The pastry stays used. If you later send "full": true, the other $4.00 and 40 Beans are reversed, the redemption becomes reversed, and the pastry goes back to her wallet if it hasn't expired. The Checkout guide shows a full refund with a points_shortfall.

Warning Send every refund you make. If you skip them, guests keep points for food they got back, and the program's reports overstate sales.

POST/v1/orders/{id}/refunds

1
2
3
4
5
6
7
8
9curl -X POST $UNPLUG_API/orders/c9e5a3f1-7d2b-4e8c-a0f6-3b1d9e5c7a24/refunds \
  -H "Authorization: Bearer $UNPLUG_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d2a9f4c-1e6b-4c8d-b3a5-8f0e2c6d9a14" \
  -d '{
    "external_refund_id": "rf-30417-1",
    "amount_cents": 500,
    "reason": "requested_by_customer"
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14const response = await fetch(`${process.env.UNPLUG_API}/orders/c9e5a3f1-7d2b-4e8c-a0f6-3b1d9e5c7a24/refunds`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UNPLUG_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "7d2a9f4c-1e6b-4c8d-b3a5-8f0e2c6d9a14",
  },
  body: JSON.stringify({
    external_refund_id: "rf-30417-1",
    amount_cents: 500,
    reason: "requested_by_customer",
  }),
});
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']}/orders/c9e5a3f1-7d2b-4e8c-a0f6-3b1d9e5c7a24/refunds",
    headers={
        "Authorization": f"Bearer {os.environ['UNPLUG_KEY']}",
        "Idempotency-Key": "7d2a9f4c-1e6b-4c8d-b3a5-8f0e2c6d9a14",
    },
    json={
        "external_refund_id": "rf-30417-1",
        "amount_cents": 500,
        "reason": "requested_by_customer",
    },
)
data = response.json()

Response JSON201

1
2
3
4
5
6
7
8
9
10
11
12
13
14{
  "id": "e2b6d8f0-4a1c-4e7b-9d3f-6c8a0b2e5d71",
  "order_id": "c9e5a3f1-7d2b-4e8c-a0f6-3b1d9e5c7a24",
  "external_refund_id": "rf-30417-1",
  "amount_cents": 500,
  "full": false,
  "reason": "requested_by_customer",
  "points_reversed": 50,
  "points_shortfall": 0,
  "order_status": "partially_refunded",
  "member_id": "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
  "member": { "points_balance": 460 },
  "created_at": "2026-11-05T15:02:17Z"
}

Error descriptions#

400Bad request

idempotency_key_required

The Idempotency-Key header is missing.

400Bad request

invalid_request

Both or neither of amount_cents and full were sent.

404Not found

not_found

No order with this id in your brand.

422Unprocessable

refund_exceeds_order

This refund plus earlier ones would be more than the order's subtotal after discounts, or the order is already fully refunded.

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