☰ Menu · Transactions
Transactions
A closed check sent by a till. It earns, it can redeem cashback, it can be voided.
The transaction object
- external_idstring
- Your check id. Unique per venue.
- statusstring
completedorvoided.- amountinteger
- The full check, minor units.
- redeem_amountinteger
- Paid with cashback.
- net_amountinteger
amount − redeem_amount.- cashback_earned, stamps_earnedinteger
- What the check earned.
- reward_unlockedboolean
- This check completed a stamp card.
- currency, register_id, closed_atstring
- As sent.
- locationobject
- Only when the check fell on a location with its own rules:
{id, name, store_code, register_id, matched_by}.matched_byisregister_idorstore_id. See how to send the location and the register. - cashierobject
- Only when the check was sent with
cashier:{id, name}. - memberobject
- The member after the check, with the new balance.
- amount_refundedinteger
- Total of partial refunds so far.
- line_itemsarray
- The check's lines with what each one did:
amount(the line's share of the check),cashback_earned,earn_percent(null when the category earns nothing),redeemable(could be paid with cashback) andquantity_refunded. Empty when the check came without lines. - line_items[].promoboolean
- Only for venues with promo rules: whether the line was sent as an item on promotion.
- displayobject
cashier_textandreceipt_linesin the guest's language, ready to print.
/v1/transactionsApplies one closed check. Repeating an external_id returns the stored result with 200. card_number and gross_amount are accepted as aliases of member and amount.
- external_idstring, required
- Your check id, up to 128 characters.
- memberstring, required
- Card number, scanned value, serial, member id or phone.
- amountinteger, required
- The full check before cashback, minor units, above zero.
- redeem_amountinteger
- Cashback the guest uses on this check. Default 0. Capped by the balance and the program's
redeem_max_percent. - currencystring
- ISO 4217. Default: the program currency.
- closed_atdatetime
- When the check closed, ISO 8601 with offset. Default: now.
- register_idstring
- Your till or location id. Shown in reports. When the owner binds this code to a location, the check follows that location's cashback rules.
- 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 rang the check, as your till knows them: a string (name or code) or
{id, name}. Stored with the check and returned ascashier. It never changes cashback and is left out of the idempotency check. The owner's cashier signals use it to show who rang a suspicious check. - hold_iduuid
- Capture this hold instead of sending
redeem_amount. - discount_typestring
- Your discount code on this check (
employee,discount_card,promo), up to 64 characters. With discount types on, the owner's rules for it apply. A line can carry its owndiscount_typetoo. - 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.- line_itemsarray
- Up to 500 of
{sku, name, quantity, unit_price, category}. Stored with the check for product reports and used by category rules: a category that earns no cashback, cannot be paid with cashback (promotional items) or earns its own percent. Withoutcategorywe look the category up byskuin the catalog. Without line items the whole check earns at the guest's level.
How to send the location and the register
Send two optional strings with every check (POST /v1/transactions), calculation (POST /v1/checks/calculate) and hold (POST /v1/holds): register_id is the code of the register, store_id is the code of the store (location) in your accounting system, up to 64 characters. The owner enters both codes under Locations. The location is found by register_id first; when the register code is missing or bound to no location, by store_id. When both are sent and point to different locations, register_id wins. When nothing matches, the check follows the general rules and the unknown codes appear to the owner in the "unbound" list. The codes work when the venue has location rules on; otherwise the fields are ignored. Send both fields with every check, even with a single location.
{
"external_id": "000131",
"member": "2000111703779",
"amount": 12550,
"store_id": "122927",
"register_id": "122930",
"line_items": [
{ "sku": "4840001", "name": "Corona 0.33", "quantity": 2, "unit_price": 3500, "category": "106" },
{ "sku": "2040", "name": "Paine", "quantity": 1, "unit_price": 5550 }
]
}The calculation and the transaction then carry a location object with the location the check was counted at: id, name, store_code, register_id and matched_by (register_id or store_id). No location in the answer means the check followed the general rules.
{
"object": "transaction",
"external_id": "000131",
"register_id": "122930",
...
"location": {
"object": "location",
"id": "3c1f5a7e-2b9d-4e60-8f14-6a0d2c7b9e35",
"name": "Store 1",
"store_code": "122927",
"register_id": "122930",
"matched_by": "register_id"
}
}curl https://loyaltyfy.io/api/v1/transactions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"external_id": "CHK-2026-000123",
"member": "2000111703779",
"amount": 25000,
"currency": "MDL",
"register_id": "POS-1",
"store_id": "S-1",
"closed_at": "2026-10-06T18:17:00+03:00",
"line_items": [
{ "sku": "1001", "name": "Espresso", "quantity": 2, "unit_price": 4000, "category": "Coffee" },
{ "sku": "2005", "name": "Cheesecake", "quantity": 1, "unit_price": 17000, "category": "Desserts" }
]
}'{
"object": "transaction",
"id": "f8acbb16-0b3b-4afc-acbb-e5eabd4dd072",
"external_id": "CHK-2026-000123",
"status": "completed",
"amount": 25000,
"redeem_amount": 0,
"cashback_earned": 1250,
"stamps_earned": 0,
"reward_unlocked": false,
"net_amount": 25000,
"currency": "MDL",
"register_id": "POS-1",
"closed_at": "2026-10-06T15:17:00+00:00",
"livemode": false,
"created_at": "2026-10-06T18:17:17.921+00:00",
"voided_at": null,
"amount_refunded": 0,
"line_items": [
{ "sku": "1001", "name": "Espresso", "quantity": 2, "unit_price": 4000, "category": "Coffee", "amount": 8000, "earn_percent": 5, "cashback_earned": 400, "redeemable": true, "quantity_refunded": 0 },
{ "sku": "2005", "name": "Cheesecake", "quantity": 1, "unit_price": 17000, "category": "Desserts", "amount": 17000, "earn_percent": 5, "cashback_earned": 850, "redeemable": true, "quantity_refunded": 0 }
],
"member": {
"object": "member",
"id": "6dacfe0a-2500-44c6-a37c-05c660b093b4",
"card_number": "2000111703779",
"cashback": { "balance": 1250, "currency": "MDL", "earn_rate": 5, ... },
...
}
}/v1/transactions/{external_id}Returns one transaction by your check id.
/v1/transactions/{external_id}/voidUndoes a check: earned cashback and stamps are taken back, redeemed cashback is returned. Voiding twice is harmless.
curl -X POST https://loyaltyfy.io/api/v1/transactions/CHK-2026-000123/void \
-H "Authorization: Bearer sk_test_..."{
"object": "transaction",
"id": "f8acbb16-0b3b-4afc-acbb-e5eabd4dd072",
"external_id": "CHK-2026-000123",
"status": "voided",
"amount": 25000,
"cashback_earned": 1250,
"voided_at": "2026-10-06T18:17:21.003+00:00",
"member": {
"object": "member",
"id": "6dacfe0a-2500-44c6-a37c-05c660b093b4",
"card_number": "2000111703779",
"cashback": { "balance": 0, "currency": "MDL", "earn_rate": 5, ... },
...
},
...
}/v1/transactions/{external_id}/refundsReturns part of a cashback check, by amount or by line_items. By amount, cashback moves in proportion to the check. By lines, cashback moves by what each line really earned: a promo item that earned nothing takes nothing back, and cashback the guest spent is restored only for lines it could pay for. Send the refund's own external_id; repeating it is safe. Several refunds per check are allowed; the last one settles exact remainders. Stamp and visit checks are refunded in full with void.
- external_idstring, required
- Your id of this refund, up to 128 characters.
- amountinteger
- The returned sum in minor units. Leave it out when
line_itemssay what came back. - line_itemsarray
- The returned lines:
{sku, quantity}or{name, quantity}, exactly as on the check. Units already returned are counted; asking for more answersrefund_exceeds_linewithrefundable. A check sent without lines answersno_line_items: refund it by amount. - line_items[].promoboolean
- Accepted and ignored: the refund follows what the original line earned and could pay for.
- register_idstring
- Your register id, for per-register numbering.
- store_idstring
- Your store code. Accepted for symmetry with the check; the refund follows the location of the original check.
# the guest returns 50.00 of a 200.00 check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000124/refunds \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{ "external_id": "RET-2026-000017", "amount": 5000 }'
# or: the guest brings back one Latte out of the lines on the check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000130/refunds \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{ "external_id": "RET-2026-000018", "line_items": [{ "sku": "1001", "quantity": 1 }] }'
# the Latte earned 4.50 at its own 10%, so exactly 4.50 is taken back{
"object": "refund",
"id": "c41d2f7a-3b9e-4c11-8e0f-6a2d5b7c9e13",
"external_id": "RET-2026-000017",
"transaction": "CHK-2026-000124",
"amount": 5000,
"cashback_reversed": 200,
"redeem_restored": 1000,
"line_items": [],
"livemode": false,
"created_at": "2026-10-06T18:40:02.000+00:00",
"transaction_after": { "object": "transaction", "amount_refunded": 5000, "member": { ... }, ... }
}
// by lines
{
"object": "refund",
"external_id": "RET-2026-000018",
"transaction": "CHK-2026-000130",
"amount": 4500,
"cashback_reversed": 450,
"redeem_restored": 0,
"line_items": [
{ "sku": "1001", "name": "Latte", "quantity": 1, "amount": 4500, "cashback_reversed": 450, "redeem_restored": 0 }
],
...
}/v1/transactions/{external_id}/returnsReturns one or more lines of a check: the guest brings back one item out of three. Cashback earned on those lines is taken back and cashback the guest paid for them is given back, by what each line really earned and could pay for, never in proportion to the check. The response is the same object as a refund with object: "return". Send the return's own external_id; repeating it is safe. Checks sent without line_items cannot be returned by line: refund them by amount.
- external_idstring, required
- Your id of this return, up to 128 characters.
- line_itemsarray, required
- The returned lines:
{sku, quantity}or{name, quantity}, exactly as on the check. Units already returned are counted; asking for more answersrefund_exceeds_linewithrefundable. - line_items[].promoboolean
- Accepted and ignored: the refund follows what the original line earned and could pay for.
- register_idstring
- Your register id, for per-register numbering.
- store_idstring
- Your store code. Accepted for symmetry with the check; the refund follows the location of the original check.
# the guest brings back one Latte out of the lines on the check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000130/returns \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{ "external_id": "RET-2026-000019", "line_items": [{ "sku": "1001", "quantity": 1 }] }'
# the Latte earned 4.50 at its own 10%, so exactly 4.50 is taken back{
"object": "return",
"id": "9f1c2b8e-5d7a-4e3f-9b21-0c4d6e8f1a23",
"external_id": "RET-2026-000019",
"transaction": "CHK-2026-000130",
"amount": 4500,
"cashback_reversed": 450,
"redeem_restored": 0,
"line_items": [
{ "sku": "1001", "name": "Latte", "quantity": 1, "amount": 4500, "cashback_reversed": 450, "redeem_restored": 0 }
],
"livemode": false,
"created_at": "2026-11-06T09:12:40.000+00:00",
"transaction_after": { "object": "transaction", "amount_refunded": 4500, "line_items": [ ... ], "member": { ... }, ... }
}/v1/transactionsLists transactions, newest first. Filter with ?member=. Paginated.