☰ 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_idwith the check. - memberstring
- The card number.
- amountinteger
- Cashback set aside, minor units.
- statusstring
active,captured,releasedorexpired.- captured_bystring or null
external_idof the check that used it.- expires_atdatetime
- When an unused hold is released on its own.
POST
/v1/holdsScope: 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_idis missing or bound to no location. When both point to different locations,register_idwins. 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 ascashier; a check that captures the hold without its owncashiertakes this one. - line_itemsarray
- For category rules.
- line_items[].promoboolean
truewhen 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}/releaseScope: 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).