> ## Documentation Index
> Fetch the complete documentation index at: https://help.lobyco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Returns and refunds

> Record a customer's return as a purchase, so Lobyco gives back the coupons it completes.

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](https://help.lobyco.com/api-reference/retail-master-data/purchases/post-v1-purchases.md), with its `discounts` and each product's `discountAllocations`. The [Discount integration](https://help.lobyco.com/integration/pos-point-of-sale-integrations/discount-integration.md) response holds both.
* The coupons on the sale were redeemed with its `receiptId`, as described on [Coupon redemption at POS](https://help.lobyco.com/integration/pos-point-of-sale-integrations/coupon-redemption-at-pos.md#redeem-the-coupons).

## The flow

```mermaid theme={"system"}
sequenceDiagram
    participant Customer
    participant POS
    participant Discount as Discount API
    participant Purchase as Purchase API
    participant Coupons as Lobyco coupons
    Customer->>POS: Brings items back
    opt Recommended refund
        POS->>Discount: Return purchase
        Discount-->>POS: Amount to<br/>pay back
    end
    POS->>Customer: Pays back
    POS->>Purchase: Return purchase
    Purchase-->>POS: 200 OK
    Purchase-)Coupons: Return loaded
    Coupons->>Coupons: Gives back<br/>completed coupons
```

**Step 1**

### 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`.

```json theme={"system"}
{
  "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"
    }
  ]
}
```

**Step 2**

### \[Optional] Get the recommended refund

[POST /v1/discounted-purchases](https://help.lobyco.com/api-reference/promotion-platform/discounts/post-v1-discounted-purchases.md)

Send 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](https://help.lobyco.com/integration/pos-point-of-sale-integrations/returns-and-refunds/recommended-refund.md).

**Step 3**

### Record the return

[POST /v1/purchases](https://help.lobyco.com/api-reference/retail-master-data/purchases/post-v1-purchases.md)

Send the return once the customer is paid back, with the amount actually paid back as each product's `price`. It meets the same [validations](https://help.lobyco.com/integration/pos-point-of-sale-integrations/transaction-data.md#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](https://help.lobyco.com/integration/pos-point-of-sale-integrations/returns-and-refunds/coupon-refund.md).

## 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](https://help.lobyco.com/integration/pos-point-of-sale-integrations/coupon-redemption-at-pos.md#returns-and-refunds).
* **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](https://help.lobyco.com/api-reference/promotion-platform/discounts), [Purchases](https://help.lobyco.com/api-reference/retail-master-data/purchases) and [Coupons (POS)](https://help.lobyco.com/api-reference/promotion-platform/coupons-pos).

## Related

* [Recommended refund](https://help.lobyco.com/integration/pos-point-of-sale-integrations/returns-and-refunds/recommended-refund.md) — the amount Lobyco recommends paying back for each returned product.
* [Coupon refund](https://help.lobyco.com/integration/pos-point-of-sale-integrations/returns-and-refunds/coupon-refund.md) — when a return gives a coupon back, with worked examples.
* [Coupon redemption at POS](https://help.lobyco.com/integration/pos-point-of-sale-integrations/coupon-redemption-at-pos.md) — the redeem call that carries the `receiptId`, and cancel-redeem for giving coupons back by hand.
* [Transaction data](https://help.lobyco.com/integration/pos-point-of-sale-integrations/transaction-data.md) — the validation rules a return meets like any other purchase.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.