☰ Menu · Transactions
API reference

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
completed or voided.
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_by is register_id or store_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) and quantity_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_text and receipt_lines in the guest's language, ready to print.
POST/v1/transactions
Scope: transactions:write

Applies 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_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 rang the check, as your till knows them: a string (name or code) or {id, name}. Stored with the check and returned as cashier. 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 own discount_type too.
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.
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. Without category we look the category up by sku in 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.

Request · POST /v1/transactions
{
  "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.

Response · 201 (excerpt)
{
  "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
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" }
    ]
  }'
Response · 201
{
  "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, ... },
    ...
  }
}
GET/v1/transactions/{external_id}
Scope: transactions:write

Returns one transaction by your check id.

POST/v1/transactions/{external_id}/void
Scope: transactions:write

Undoes a check: earned cashback and stamps are taken back, redeemed cashback is returned. Voiding twice is harmless.

curl
curl -X POST https://loyaltyfy.io/api/v1/transactions/CHK-2026-000123/void \
  -H "Authorization: Bearer sk_test_..."
Response · 200
{
  "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, ... },
    ...
  },
  ...
}
POST/v1/transactions/{external_id}/refunds
Scope: transactions:write

Returns 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_items say 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 answers refund_exceeds_line with refundable. A check sent without lines answers no_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.
curl
# 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
Response · 201
{
  "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 }
  ],
  ...
}
POST/v1/transactions/{external_id}/returns
Scope: transactions:write

Returns 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 answers refund_exceeds_line with refundable.
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.
curl
# 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
"Response · 201"
{
  "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": { ... }, ... }
}
GET/v1/transactions
Scope: transactions:write

Lists transactions, newest first. Filter with ?member=. Paginated.

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