Returns and refunds - Lobyco Help center

When a customer brings items back, Lobyco recommends how much to pay back, and the POS decides. The POS pays the customer and records the return as a purchase. Lobyco then gives back every coupon whose discounted items have all come back.

Before you start

Lobyco has turned refunds on for your environment. They are off by default, and until then a return gives no coupons back.
The return carries the same memberId as the original sale. Lobyco handles returns of customer purchases only.
The original sale was recorded with POST /v1/purchases, with its discounts and each product’s discountAllocations. The Discount integration response holds both.
The coupons on the sale were redeemed with its receiptId, as described on Coupon redemption at POS.

The flow

Build the return purchase

Give the return a new receiptId, and mark each returned product:

originalReceiptId, the receiptId of the sale the product was bought on. Lobyco links the return to the sale through it, so one return can hold products from several sales.
isReturned, set to true.
quantity, the units coming back.
price, negative, as on any returned product.

There is no field for the line of the original receipt. Lobyco matches returned products to the sale by id.

{
  "receiptId": "RETURN-1",
  "memberId": "12396909",
  "totalAmount": -19.16,
  "products": [
    {
      "sequenceNumber": 1,
      "id": "yoghurt",
      "quantity": { "value": -2, "unitOfMeasure": "EA" },
      "price": -6.66,
      "isReturned": true,
      "originalReceiptId": "SALE-1"
    },
    {
      "sequenceNumber": 2,
      "id": "coffee",
      "quantity": { "value": -1, "unitOfMeasure": "EA" },
      "price": -12.50,
      "isReturned": true,
      "originalReceiptId": "SALE-2"
    }
  ]
}

[Optional] Get the recommended refund

POST /v1/discounted-purchasesSend the return purchase to the same endpoint a sale uses. Lobyco answers with the amount it recommends paying back for each returned product. The POS can pay back that amount or a different one. See Recommended refund.

Record the return

POST /v1/purchasesSend the return once the customer is paid back, with the amount actually paid back as each product’s price. It meets the same validations as a sale. The Purchase API answers 200 OK once it has stored the return.

What happens next

Shortly after loading the return, Lobyco checks the coupons redeemed on each original receipt. It gives back each coupon whose discounted products are now all back. The rules and examples are on Coupon refund.

Failure and edge cases

If the recommended refund or the coupons are not what you expect, it is one of these.

Part of what the coupon discounted is still with the customer. The coupon stays used until the rest comes back.
The return has no memberId. Coupons come back only on a customer’s return. Send the return with the same memberId as the original sale.
The coupon was redeemed without the sale’s receiptId. Lobyco cannot match it to the return. Give it back with cancel-redeem, as described on Coupon redemption at POS.
The originalReceiptId is wrong. Lobyco finds no sale with that id. Those products keep the price the POS sent, and no coupon comes back for them.
Two returns of one sale come close together. Lobyco counts an earlier return only once it has processed it, shortly after the POS records it. A return priced before then is recommended as if the earlier one had not happened. Check the amount against what the POS already paid back for that receipt.
The same return is loaded twice. Lobyco records each return once, so the second load gives nothing back.
The POS already gave the coupon back. Lobyco skips a redemption that cancel-redeem has already cancelled.

API reference

Endpoint documentation: Discounts, Purchases and Coupons (POS).

Recommended refund — the amount Lobyco recommends paying back for each returned product.
Coupon refund — when a return gives a coupon back, with worked examples.
Coupon redemption at POS — the redeem call that carries the receiptId, and cancel-redeem for giving coupons back by hand.
Transaction data — the validation rules a return meets like any other purchase.

​Before you start

​The flow

​Build the return purchase

​[Optional] Get the recommended refund

​Record the return

​What happens next

​Failure and edge cases

​API reference

​Related