Returns
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 POST request to the /api/{version}/sales/:id/actions/return endpoint (Init Return endpoint) for date-versioned APIs. This will generate a new 'parked' sale. The id in the POST request must be of an existing closed sale.
While we strongly recommend migrating to the date-versioned APIs, clients using the legacy 2.0 API should continue to use PUT with /api/2.0/sales/:id/actions/return.
For this example we're using the following URL:
https://<<domain_prefix>>.retail.lightspeed.app/api/{version}/sales/0698ab21-5fd8-11f1-f954-5ec02d6bd851/actions/returnThis 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-5ec05a8067b5This 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-5ec05a8067b5With 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.