☰ Menu · Holds
API reference

Holds

Cashback set aside at the scan and confirmed by the closed check.

The hold object

iduuid
Send it as hold_id with the check.
memberstring
The card number.
amountinteger
Cashback set aside, minor units.
statusstring
active, captured, released or expired.
captured_bystring or null
external_id of the check that used it.
expires_atdatetime
When an unused hold is released on its own.
POST/v1/holds
Scope: transactions:write

Sets cashback aside. The same caps as for a check apply; asking for more is refused with 402 insufficient_balance and limited_by. Send an Idempotency-Key.

memberstring, required
Card number, scanned value, serial, member id or phone.
amountinteger, required
Cashback to set aside.
check_amountinteger, required
The check total, for the program's share and the category rules.
register_idstring
Your register id. If it is bound to a location where paying with cashback is not allowed, the hold is refused with redeem_not_allowed_here.
store_idstring
The store (location) code from your accounting system, up to 64 characters. Used when register_id is missing or bound to no location. When both point to different locations, register_id wins. See how to send the location and the register.
cashierstring or object
Who is ringing the check: a string or {id, name}. Kept on the hold and returned as cashier; a check that captures the hold without its own cashier takes this one.
line_itemsarray
For category rules.
line_items[].promoboolean
true when the item is on promotion. The owner's promo rules then decide whether the line earns and whether it can be paid with cashback. Ignored where the venue has not turned the rule on.
curl
curl https://loyaltyfy.io/api/v1/holds \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hold-R3-000131" \
  -d '{ "member": "2000111703779", "amount": 3000, "check_amount": 20000, "register_id": "R3" }'

# at payment: the check captures it
curl https://loyaltyfy.io/api/v1/transactions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "000131", "register_id": "R3", "member": "2000111703779",
        "amount": 20000, "hold_id": "5b0d6c1e-8f3a-4d7e-9a61-2c4b8e0f7d19" }'
Response · 201
{
  "object": "hold",
  "id": "5b0d6c1e-8f3a-4d7e-9a61-2c4b8e0f7d19",
  "member": "2000111703779",
  "amount": 3000,
  "check_amount": 20000,
  "status": "active",
  "register_id": "R3",
  "captured_by": null,
  "expires_at": "2026-10-06T19:02:11.000+00:00",
  "livemode": false,
  "created_at": "2026-10-06T18:32:11.000+00:00",
  "member_after": { "object": "member", "cashback": { "balance": 10200, "held": 3000, "available": 7200, ... }, ... }
}
GET/v1/holds/{id}
Scope: transactions:write

One hold with its current status.

POST/v1/holds/{id}/release
Scope: transactions:write

Gives the money back now. Releasing a released or expired hold is harmless; a captured hold answers 409 hold_captured (void the check instead).

Questions about an integration: api@loyaltyfy.io. We answer within one business day.