Returns

Using the following steps you will be able to handle returning a sale via the API.

1. Initiating the return.

In order to initiate a return of a sale, make a PUT request to the /api/{version}/sales/:id/actions/return endpoint (Init Return endpoint). This will generate a new 'parked' sale. The id in the PUT requestion must be of an existing closed sale.

For this example we're using the following URL:

https://<<domain_prefix>>.retail.lightspeed.app/api/{version}/sales/0698ab21-5fd8-11f1-f954-5ec02d6bd851/actions/return

This gives us the following response:

{
    "data": {
        "id": "0698ab21-5fd8-11f1-f954-5ec05a8067b5",
        "outlet_id": "0ac54c19-8cd8-11ed-f575-b396fb0c257c",
        "register_id": "0ac54c19-8cd8-11ed-f575-b396fb16526d",
        "user_id": "06326976-9d65-11ed-fa40-06af15b3193d",
        "customer_id": "06e94082-edd8-11ee-f619-c09746455863",
        "invoice_number": "1693",
        "receipt_number": "1693",
        "invoice_sequence": 1693,
        "receipt_sequence": 1693,
        "status": "SAVED",
        "state": "parked",
        "note": "",
        "short_code": "fnjoyw",
        "return_for": "0698ab21-5fd8-11f1-f954-5ec02d6bd851",
        "created_at": "2026-06-02T20:19:27+00:00",
        "total_price": -110.0,
        "total_loyalty": 0.0,
        "total_tax": 0.0,
        "updated_at": "2026-06-02T20:19:27+00:00",
        "sale_date": "2026-06-02T20:19:27+00:00",
        "deleted_at": null,
        "line_items": [
            {
                "id": "0698ab21-5fd8-11f1-f954-5ec05a7e8387",
                "product_id": "c16c5f3e-92df-49a5-a21f-9abd201f68d3",
                "quantity": -2.0,
                "price": 55.0,
                "unit_price": 55.0,
                "price_total": -110.0,
                "total_price": -110.0,
                "discount": 0.0,
                "unit_discount": 0.0,
                "discount_total": 0.0,
                "total_discount": 0.0,
                "loyalty_value": 22.22,
                "unit_loyalty_value": 22.22,
                "total_loyalty_value": -44.44,
                "cost": 0.0,
                "unit_cost": 0.0,
                "cost_total": 0.0,
                "total_cost": 0.0,
                "tax": 0.0,
                "unit_tax": 0.0,
                "tax_total": 0.0,
                "total_tax": 0.0,
                "tax_id": "06326976-9d65-11ed-fa40-06af15ad04e5",
                "tax_components": [
                    {
                        "rate_id": "15ad4653-06af-11ed-ba40-063269769d65",
                        "total_tax": 0.0
                    }
                ],
                "promotions": [],
                "price_set": true,
                "sequence": 0,
                "note": null,
                "status": "SAVED",
                "is_return": true
            }
        ],
        "payments": [],
        "taxes": [
            {
                "id": "15ad4653-06af-11ed-ba40-063269769d65",
                "name": "No Tax",
                "rate": "0.00000",
                "amount": 0.0,
                "total_tax": 0.0
            }
        ],
        "adjustments": [],
        "version": 53179667987
    }
}

The most important part of that response is the id of the highest-level object, in this case 0698ab21-5fd8-11f1-f954-5ec05a8067b5. This is the id of a new parked sale that was just created.

2. Getting the data

Call the Get Sale By Id endpoint with the id returned in Step 1 (0698ab21-5fd8-11f1-f954-5ec05a8067b5) to retrieve the parked sale.

The full GET request will look like:

https://<<domain_prefix>>.retail.lightspeed.app/api/{version}/sales/0698ab21-5fd8-11f1-f954-5ec05a8067b5

This gives us the following response:

{
    "data": {
        "id": "0698ab21-5fd8-11f1-f954-5ec05a8067b5",
        "date": "2026-06-02T20:19:27+00:00",
        "invoice_number": "1693",
        "short_code": "fnjoyw",
        "state": "parked",
        "note": "",
        "source": {
            "id": null,
            "type": "USER",
            "author": {
                "id": "06326976-9d65-11ed-fa40-06af15b3193d"
            },
            "register_id": "0ac54c19-8cd8-11ed-f575-b396fb16526d",
            "outlet_id": "0ac54c19-8cd8-11ed-f575-b396fb0c257c"
        },
        "customer_id": "06e94082-edd8-11ee-f619-c09746455863",
        "attributes": [],
        "payments": [],
        "line_items": [
            {
                "id": "0698ab21-5fd8-11f1-f954-5ec05a7e8387",
                "quantity": -2.00000,
                "product": {
                    "id": "c16c5f3e-92df-49a5-a21f-9abd201f68d3"
                },
                "pricing": {
                    "total": -110.0000000000,
                    "cost": 0.00000,
                    "discount": 0.00000,
                    "price": 55.00000,
                    "loyalty_amount": 11.11000,
                    "cost_total": 0.0000000000,
                    "discount_total": 0.0000000000,
                    "loyalty_amount_total": -22.2200000000
                },
                "tax": {
                    "id": "06326976-9d65-11ed-fa40-06af15ad04e5",
                    "amount": 0.00000,
                    "total": 0.0000000000
                },
                "status": "SAVED",
                "promotions": [],
                "note": null,
                "surcharges": [],
                "customizations": [],
                "return": {
                    "reason": null,
                    "is_return": true
                },
                "gift_card_number": null,
                "salesperson_id": null,
                "_metadata": {
                    "sequence": 0,
                    "is_price_override": true,
                    "tax_components": [
                        {
                            "rate_id": "15ad4653-06af-11ed-ba40-063269769d65",
                            "total_tax": 0.00000
                        }
                    ]
                }
            }
        ],
        "return": {
            "original_sale_id": "0698ab21-5fd8-11f1-f954-5ec02d6bd851",
            "return_sale_ids": [],
            "is_return": true
        },
        "taxes": [
            {
                "id": "15ad4653-06af-11ed-ba40-063269769d65",
                "tax": 0.00000
            }
        ],
        "totals": {
            "price": -110.00,
            "tax": 0.00,
            "loyalty": 0.00000,
            "surcharge": 0,
            "price_incl_tax": -110.0000000000
        },
        "adjustments": [],
        "external_applications": [],
        "ecom_custom_charges": [],
        "receipt_number": "1693",
        "created_at": "2026-06-02T20:19:27+00:00",
        "updated_at": "2026-06-02T20:19:27+00:00",
        "deleted_at": null,
        "_metadata": {
            "version": 53179667987,
            "xero_reference": null,
            "complete_open_sequence_id": null,
            "has_unsynced_on_account_payments": null
        }
    }
}

3. Finalizing the return

If you look above you will notice 2 things about the return sale we've just created - its state is parked and there are no payments on it. Changing those 2 things will be required to finalize the return. Update the newly created parked sale with the that monetary amount you would like to refund, and the transition the state from parked to closed.

We'll do that by making a PUT call to Update Sale endpoint with the following URL:

https://<<domain_prefix>>.retail.lightspeed.app/api/{version}/sales/0698ab21-5fd8-11f1-f954-5ec05a8067b5

With the following changes:

"state": "closed",

and

    "payments": [
        {
            "amount": -110,
            "type": {
                "id": "1",
                "name": "Cash",
                "config_id": "4578186f-de8d-4189-8f4d-a9bac42980ee"
            }
        }
    ]

The full payload will look like this:

{
    "date": "2026-06-02T20:19:27+00:00",
    "invoice_number": "1693",
    "short_code": "fnjoyw",
    "state": "closed",
    "note": "",
    "source": {
        "id": null,
        "type": "USER",
        "author": {
            "id": "06326976-9d65-11ed-fa40-06af15b3193d"
        },
        "register_id": "0ac54c19-8cd8-11ed-f575-b396fb16526d",
        "outlet_id": "0ac54c19-8cd8-11ed-f575-b396fb0c257c"
    },
    "customer_id": "06e94082-edd8-11ee-f619-c09746455863",
    "attributes": [],
    "payments": [
        {
            "amount": -110,
            "type": {
                "id": "1",
                "name": "Cash",
                "config_id": "4578186f-de8d-4189-8f4d-a9bac42980ee"
            }
        }
    ],
    "line_items": [
        {
            "id": "0698ab21-5fd8-11f1-f954-5ec05a7e8387",
            "quantity": -2.00000,
            "product": {
                "id": "c16c5f3e-92df-49a5-a21f-9abd201f68d3"
            },
            "pricing": {
                "total": -110.0000000000,
                "cost": 0.00000,
                "discount": 0.00000,
                "price": 55.00000,
                "loyalty_amount": 11.11000,
                "cost_total": 0.0000000000,
                "discount_total": 0.0000000000,
                "loyalty_amount_total": -22.2200000000
            },
            "tax": {
                "id": "06326976-9d65-11ed-fa40-06af15ad04e5",
                "amount": 0.00000,
                "total": 0.0000000000
            },
            "status": "SAVED",
            "promotions": [],
            "note": null,
            "surcharges": [],
            "customizations": [],
            "return": {
                "reason": null,
                "is_return": true
            },
            "gift_card_number": null,
            "salesperson_id": null,
            "_metadata": {
                "sequence": 0,
                "is_price_override": true,
                "tax_components": [
                    {
                        "rate_id": "15ad4653-06af-11ed-ba40-063269769d65",
                        "total_tax": 0.00000
                    }
                ]
            }
        }
    ],
    "return": {
        "original_sale_id": "0698ab21-5fd8-11f1-f954-5ec02d6bd851",
        "return_sale_ids": [],
        "is_return": true
    },
    "taxes": [
        {
            "id": "15ad4653-06af-11ed-ba40-063269769d65",
            "tax": 0.00000
        }
    ],
    "totals": {
        "price": -110.00,
        "tax": 0.00,
        "loyalty": 0.00000,
        "surcharge": 0,
        "price_incl_tax": -110.0000000000
    },
    "adjustments": [],
    "external_applications": [],
    "ecom_custom_charges": [],
    "receipt_number": "1693",
    "created_at": "2026-06-02T20:19:27+00:00",
    "updated_at": "2026-06-02T20:19:27+00:00",
    "deleted_at": null,
    "_metadata": {
        "version": 53179667987,
        "xero_reference": null,
        "complete_open_sequence_id": null,
        "has_unsynced_on_account_payments": null
    }
}

This should result in the following response:

{
    "data": {
        "id": "0698ab21-5fd8-11f1-f954-5ec05a8067b5",
        "date": "2026-06-02T20:19:27+00:00",
        "invoice_number": "1693",
        "short_code": "fnjoyw",
        "state": "closed",
        "note": "",
        "source": {
            "id": null,
            "type": "USER",
            "register_id": "0ac54c19-8cd8-11ed-f575-b396fb16526d",
            "outlet_id": "0ac54c19-8cd8-11ed-f575-b396fb0c257c",
            "author": {
                "id": "06326976-9d65-11ed-fa40-06af15b3193d"
            }
        },
        "customer_id": "06e94082-edd8-11ee-f619-c09746455863",
        "attributes": [],
        "payments": [
            {
                "id": "0698ab21-5fd8-11f1-f954-5ec39b1516a3",
                "date": "2026-06-02T20:19:27+00:00",
                "amount": -110,
                "type": {
                    "id": "1",
                    "name": "Cash",
                    "config_id": "4578186f-de8d-4189-8f4d-a9bac42980ee"
                },
                "source": {
                    "id": null,
                    "register_id": "0ac54c19-8cd8-11ed-f575-b396fb16526d",
                    "outlet_id": "0ac54c19-8cd8-11ed-f575-b396fb0c257c"
                },
                "surcharge": null,
                "external_attributes": [],
                "external_applications": [],
                "deleted_at": null,
                "billing_address_id": null,
                "_metadata": {
                    "register_open_sequence_id": "0698ab21-5fd8-11f1-f6d9-247e3863af6e"
                }
            }
        ],
        "line_items": [
            {
                "id": "0698ab21-5fd8-11f1-f954-5ec05a7e8387",
                "quantity": -2,
                "product": {
                    "id": "c16c5f3e-92df-49a5-a21f-9abd201f68d3"
                },
                "pricing": {
                    "price": 55,
                    "total": -110,
                    "discount": 0,
                    "discount_total": -0,
                    "loyalty_amount": 22.22,
                    "loyalty_amount_total": -44.44,
                    "cost": 0,
                    "cost_total": -0
                },
                "tax": {
                    "id": "06326976-9d65-11ed-fa40-06af15ad04e5",
                    "amount": 0,
                    "total": -0
                },
                "status": "CONFIRMED",
                "promotions": [],
                "return": {
                    "is_return": true,
                    "reason": null
                },
                "note": null,
                "gift_card_number": null,
                "salesperson_id": null,
                "surcharges": [],
                "customizations": [],
                "_metadata": {
                    "sequence": 0,
                    "is_price_override": true,
                    "tax_components": [
                        {
                            "rate_id": "15ad4653-06af-11ed-ba40-063269769d65",
                            "total_tax": 0
                        }
                    ]
                }
            }
        ],
        "return": {
            "is_return": true,
            "original_sale_id": "0698ab21-5fd8-11f1-f954-5ec02d6bd851",
            "return_sale_ids": []
        },
        "taxes": [
            {
                "id": "15ad4653-06af-11ed-ba40-063269769d65",
                "tax": 0
            }
        ],
        "totals": {
            "price": -110,
            "tax": 0,
            "price_incl_tax": -110,
            "loyalty": -22.22,
            "surcharge": 0
        },
        "adjustments": [],
        "external_applications": [],
        "ecom_custom_charges": [],
        "receipt_number": "1693",
        "created_at": "2026-06-02T20:19:27+00:00",
        "updated_at": "2026-06-02T20:42:43+00:00",
        "deleted_at": null,
        "_metadata": {
            "xero_reference": null,
            "version": 53180284996,
            "complete_open_sequence_id": null,
            "has_unsynced_on_account_payments": null
        }
    }
}

4. Final notes

By modifying the final payload, it is possible to only return certain products from a sale. If that is done, the "return" payment should be adjusted to reflect what is actually being returned.
It is possible to create multiple returns against a single sale.