Skip to main content
Tell Lobyco which coupons a finished sale used, so they cannot be used again. Undo that when a sale is abandoned or the goods come back. The POS does this at the end of every sale that applied coupons, from either the Direct coupon service integration or the Discount integration.

​
Before you start

  • The POS has the memberId of the checked-in customer and the couponIds the sale applied, from whichever discount flow you use.
  • The POS has a receiptId for the sale before it redeems. The same value is the idempotency key here and the receipt id on the recorded purchase, and the offline path depends on them matching.

​
The flow

1

​
Redeem the coupons

POST /v2/customers/{customerId}/coupons/redeemCall this once the sale has completed. Send four things:
  • The Idempotency-Key header, set to the receiptId. It makes a retry safe, lets multi-use coupons count correctly, and is what a later refund refers to.
  • storeId, the store where the sale happened.
  • coupons, each with the value it granted.
  • basketValue, the basket total. Together with the store, it feeds the live statistics marketers see.
Lobyco redeems every coupon it finds. If some of the ids are unknown, it still redeems the rest and returns 400 Bad Request listing the ones it could not find.
2

​
[Optional] Release the reservation

POST /api/v1/customers/{customerId}/coupons/cancel-reservationIf the sale is abandoned before you redeem, release the coupons that were reserved for it. The customer can then use them at another POS or online straight away. Send the couponIds and the same reservedBy the reservation was made with. A reservation made under a different reservedBy cannot be released this way. An unreleased reservation frees itself at its reservedUntil time.

​
Returns and refunds

POST /api/v1/customers/{customerId}/coupons/cancel-redeem When a customer returns goods, the POS can give the coupons back, so the customer can use them again while the offer is still valid. Send the Idempotency-Key the coupons were redeemed with and the coupon ids to return. Lobyco does not work out which coupons a return affects. The POS decides, and it sends one request per original redemption, because a request cancels redemptions under one key only.

​
Offline redemption

Coupon retrieval and discount calculation need Lobyco online. Redemption does not. Sometimes the coupons were applied and the sale completed, but the POS cannot reach Lobyco to redeem them. Then put the coupon ids in the couponIds field of the purchase you send to POST /v1/purchases. Lobyco redeems them when it loads the purchase. For this to work, the purchase’s receiptId must equal the Idempotency-Key you would have used in the redeem call. The matching key is how Lobyco recognises coupons that were already redeemed online, so it redeems nothing twice.

​
Failure and edge cases

A redeemed coupon is one the redeem call returned in its couponIds. Lobyco marks it as used and counts it against the offer’s redemption limits.
  • The redeem call times out. Retry with the same Idempotency-Key. Lobyco treats the retry as the same request and redeems nothing twice.
  • A coupon in the request is unknown. The response is 400 Bad Request with those ids, and the other coupons are redeemed. Log the ids. The sale itself is not affected.
  • The refund key does not match. A cancel-redeem under a different key than the redemption cancels nothing. Keep the receiptId with the sale, so a return days later can still find it.
  • The offer has ended. A coupon can be given back only while its offer is still valid. After that, Lobyco does not return the coupon.

​
API reference

Endpoint documentation: Coupons (POS).
Last modified on October 8, 2026