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, you should make a PUT request to the /api/2.0/sales/:id/actions/return endpoint. The id here should be of an existing, closed sale.
For this example we're using the following URL:
https://<<domain_prefix>>.retail.lightspeed.app/api/2.0/sales/b8ca3a65-0183-11e4-fbb5-39f7fce5e39b/actions/return
Which gives us the following response:
{
"data": {
"id": "06bf537b-c783-11e6-f6b9-7ea7909ffedd",
"outlet_id": "b1e04bd8-f019-11e3-a0f5-b8ca3a64f8f4",
"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
"user_id": "b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4",
"customer_id": "b1cabb53-f019-11e3-a0f5-b8ca3a64f8f4",
"invoice_number": "1570",
"receipt_number": "1570",
"invoice_sequence": 1570,
"receipt_sequence": 1570,
"status": "SAVED",
"note": "",
"short_code": "ovvfkk",
"return_for": "b8ca3a65-0183-11e4-fbb5-39f7fce5e39b",
"created_at": "2016-09-19T20:28:03+00:00",
"total_price": -200,
"total_loyalty": 0,
"total_tax": -30,
"updated_at": "2016-09-19T20:28:03+00:00",
"sale_date": "2016-09-19T20:28:03+00:00",
"deleted_at": null,
"line_items": [
{
"id": "06bf537b-c783-11e6-f6b9-7ea7909c64b9",
"product_id": "188a87aa-06fe-11e4-a0f5-b8ca3a64f8f4",
"quantity": -1,
"price": 200,
"unit_price": 200,
"price_total": -200,
"total_price": -200,
"discount": 0,
"unit_discount": 0,
"discount_total": 0,
"total_discount": 0,
"loyalty_value": 23,
"unit_loyalty_value": 23,
"total_loyalty_value": -23,
"cost": 100,
"unit_cost": 100,
"cost_total": -100,
"total_cost": -100,
"tax": 30,
"unit_tax": 30,
"tax_total": -30,
"total_tax": -30,
"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
"tax_components": [
{
"rate_id": "b1dfed8b-f019-11e3-a0f5-b8ca3a64f8f4",
"total_tax": 30
}
],
"price_set": true,
"sequence": 1,
"note": null,
"status": "SAVED",
"is_return": true
},
{
"id": "06bf537b-c783-11e6-f6b9-7ea7909d949a",
"product_id": "188a87aa-06fe-11e4-a0f5-b8ca3a64f8f4",
"quantity": -1,
"price": 0,
"unit_price": 0,
"price_total": 0,
"total_price": 0,
"discount": 0,
"unit_discount": 0,
"discount_total": 0,
"total_discount": 0,
"loyalty_value": 0,
"unit_loyalty_value": 0,
"total_loyalty_value": 0,
"cost": 100,
"unit_cost": 100,
"cost_total": -100,
"total_cost": -100,
"tax": 0,
"unit_tax": 0,
"tax_total": 0,
"total_tax": 0,
"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
"tax_components": [
{
"rate_id": "b1dfed8b-f019-11e3-a0f5-b8ca3a64f8f4",
"total_tax": 0
}
],
"price_set": true,
"sequence": 0,
"note": null,
"status": "SAVED",
"is_return": true
}
],
"payments": [],
"taxes": [],
"version": 1978890425
}
}
The most important part of that response is the id of the highest-level object, in this case 06bf537b-c783-11e6-f6b9-7ea7909ffedd. This is an id of a new parked (status = SAVED) sale that was just created in the account.
2. Getting the data
Now, using the good, old /api/register_sales/:id endpoint you should GET all the data for that sale.
In our case, it will be a GET request to:
https://<<domain_prefix>>.retail.lightspeed.app/api/register_sales/06bf537b-c783-11e6-f6b9-7ea7909ffedd
Which gives us the following response:
{
"register_sales": [
{
"id": "06bf537b-c783-11e6-f6b9-7ea7909ffedd",
"source": "USER",
"source_id": "",
"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
"market_id": "1",
"customer_id": "b1cabb53-f019-11e3-a0f5-b8ca3a64f8f4",
"customer_name": "",
"customer": {
"id": "b1cabb53-f019-11e3-a0f5-b8ca3a64f8f4",
"name": "",
"customer_code": "WALKIN",
"customer_group_id": "b1ca8902-f019-11e3-a0f5-b8ca3a64f8f4",
"customer_group_name": "All Customers",
"enable_loyalty": 0,
"loyalty_balance": "0",
"updated_at": "2014-08-01 00:14:49",
"deleted_at": "",
"balance": "0",
"year_to_date": "0",
"date_of_birth": "",
"sex": "",
"custom_field_1": "",
"custom_field_2": "",
"custom_field_3": "",
"custom_field_4": "",
"note": "",
"contact": {}
},
"user_id": "b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4",
"user_name": "[email protected]",
"sale_date": "2016-09-19 20:28:03",
"created_at": "2016-09-19 20:28:03",
"updated_at": "2016-09-19 20:28:03",
"total_price": -200,
"total_cost": -200,
"total_tax": -30,
"tax_name": "GST",
"note": "",
"status": "SAVED",
"short_code": "ovvfkk",
"invoice_number": "1570",
"return_for": "b8ca3a65-0183-11e4-fbb5-39f7fce5e39b",
"register_sale_products": [
{
"id": "06bf537b-c783-11e6-f6b9-7ea7909d949a",
"product_id": "188a87aa-06fe-11e4-a0f5-b8ca3a64f8f4",
"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
"sequence": "0",
"handle": "mofo",
"sku": "10006",
"name": "mofo",
"quantity": -1,
"price": 0,
"cost": 100,
"price_set": 1,
"discount": 0,
"loyalty_value": 0,
"tax": 0,
"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
"tax_name": "GST",
"tax_rate": 0.15,
"tax_total": 0,
"price_total": 0,
"display_retail_price_tax_inclusive": "1",
"status": "SAVED",
"attributes": [
{
"name": "is_return",
"value": "1"
}
]
},
{
"id": "06bf537b-c783-11e6-f6b9-7ea7909c64b9",
"product_id": "188a87aa-06fe-11e4-a0f5-b8ca3a64f8f4",
"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
"sequence": "1",
"handle": "mofo",
"sku": "10006",
"name": "mofo",
"quantity": -1,
"price": 200,
"cost": 100,
"price_set": 1,
"discount": 0,
"loyalty_value": 23,
"tax": 30,
"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
"tax_name": "GST",
"tax_rate": 0.15,
"tax_total": -30,
"price_total": -200,
"display_retail_price_tax_inclusive": "1",
"status": "SAVED",
"attributes": [
{
"name": "is_return",
"value": "1"
}
]
}
],
"totals": {
"total_tax": -30,
"total_price": -200,
"total_payment": 0,
"total_to_pay": -230
},
"register_sale_payments": []
}
]
}
3. Finalizing the return
If you look above you will notice 2 things about the return sale we've just created. Its status is SAVED and it has no payments on it. Changing those 2 things will be required to finalize the return.
We'll do that by POSTing a slightly modified payload from above back to the /api/register_sales endpoint. It's important to note that there is no id included in the URL for this request: The changes are:
https://<<domain_prefix>>.retail.lightspeed.app/api/register_sales
The changes are:
"status": "CLOSED",
and
"register_sale_payments": [{
"retailer_payment_type_id": "b1e1d70e-f019-11e3-a0f5-b8ca3a64f8f4",
"amount": -230
}]
The full payload will look like this:
{
"id": "06bf537b-c783-11e6-f6b9-7ea7909ffedd",
"source": "USER",
"source_id": "",
"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
"market_id": "1",
"customer_id": "b1cabb53-f019-11e3-a0f5-b8ca3a64f8f4",
"customer_name": "",
"customer": {
"id": "b1cabb53-f019-11e3-a0f5-b8ca3a64f8f4",
"name": "",
"customer_code": "WALKIN",
"customer_group_id": "b1ca8902-f019-11e3-a0f5-b8ca3a64f8f4",
"customer_group_name": "All Customers",
"enable_loyalty": 0,
"loyalty_balance": "0",
"updated_at": "2014-08-01 00:14:49",
"deleted_at": "",
"balance": "0",
"year_to_date": "0",
"date_of_birth": "",
"sex": "",
"custom_field_1": "",
"custom_field_2": "",
"custom_field_3": "",
"custom_field_4": "",
"note": "",
"contact": {}
},
"user_id": "b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4",
"user_name": "[email protected]",
"sale_date": "2016-09-19 20:28:03",
"created_at": "2016-09-19 20:28:03",
"updated_at": "2016-09-19 20:28:03",
"total_price": -200,
"total_cost": -200,
"total_tax": -30,
"tax_name": "GST",
"note": "",
"status": "CLOSED",
"short_code": "ovvfkk",
"invoice_number": "1570",
"return_for": "b8ca3a65-0183-11e4-fbb5-39f7fce5e39b",
"register_sale_products": [{
"id": "06bf537b-c783-11e6-f6b9-7ea7909d949a",
"product_id": "188a87aa-06fe-11e4-a0f5-b8ca3a64f8f4",
"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
"sequence": "0",
"handle": "mofo",
"sku": "10006",
"name": "mofo",
"quantity": -1,
"price": 0,
"cost": 100,
"price_set": 1,
"discount": 0,
"loyalty_value": 0,
"tax": 0,
"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
"tax_name": "GST",
"tax_rate": 0.15,
"tax_total": 0,
"price_total": 0,
"display_retail_price_tax_inclusive": "1",
"status": "SAVED",
"attributes": [{
"name": "is_return",
"value": "1"
}]
}, {
"id": "06bf537b-c783-11e6-f6b9-7ea7909c64b9",
"product_id": "188a87aa-06fe-11e4-a0f5-b8ca3a64f8f4",
"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
"sequence": "1",
"handle": "mofo",
"sku": "10006",
"name": "mofo",
"quantity": -1,
"price": 200,
"cost": 100,
"price_set": 1,
"discount": 0,
"loyalty_value": 23,
"tax": 30,
"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
"tax_name": "GST",
"tax_rate": 0.15,
"tax_total": -30,
"price_total": -200,
"display_retail_price_tax_inclusive": "1",
"status": "SAVED",
"attributes": [{
"name": "is_return",
"value": "1"
}]
}],
"totals": {
"total_tax": -30,
"total_price": -200,
"total_payment": 0,
"total_to_pay": -230
},
"register_sale_payments": [{
"retailer_payment_type_id": "b1e1d70e-f019-11e3-a0f5-b8ca3a64f8f4",
"amount": -230
}]
}
This should result in the following response:
{
"register_sale": {
"id": "06bf537b-c783-11e6-f6b9-7ea7909ffedd",
"source": "USER",
"source_id": "",
"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
"market_id": "1",
"customer_id": "b1cabb53-f019-11e3-a0f5-b8ca3a64f8f4",
"customer_name": " ",
"customer": {
"id": "b1cabb53-f019-11e3-a0f5-b8ca3a64f8f4",
"name": " ",
"customer_code": "WALKIN",
"customer_group_id": "b1ca8902-f019-11e3-a0f5-b8ca3a64f8f4",
"customer_group_name": "All Customers",
"first_name": "",
"last_name": "",
"company_name": "",
"phone": "",
"mobile": "",
"fax": "",
"email": "",
"twitter": "",
"website": "",
"physical_address1": "",
"physical_address2": "",
"physical_suburb": "",
"physical_city": "",
"physical_postcode": "",
"physical_state": "",
"physical_country_id": "",
"postal_address1": "",
"postal_address2": "",
"postal_suburb": "",
"postal_city": "",
"postal_postcode": "",
"postal_state": "",
"postal_country_id": "",
"enable_loyalty": 0,
"loyalty_balance": "0",
"updated_at": "2014-08-01 00:14:49",
"deleted_at": "",
"balance": "0",
"year_to_date": "0",
"date_of_birth": "",
"sex": "",
"custom_field_1": "",
"custom_field_2": "",
"custom_field_3": "",
"custom_field_4": "",
"note": "",
"contact": {
"company_name": "",
"phone": "",
"email": ""
}
},
"user_id": "b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4",
"user_name": "[email protected]",
"sale_date": "2016-09-19 20:28:03",
"created_at": "2016-09-19 20:28:03",
"updated_at": "2016-09-19 20:56:39",
"total_price": -200,
"total_cost": -200,
"total_tax": -30,
"tax_name": "GST",
"note": "",
"status": "CLOSED",
"short_code": "ovvfkk",
"invoice_number": "1570",
"return_for": "b8ca3a65-0183-11e4-fbb5-39f7fce5e39b",
"register_sale_products": [
{
"id": "06bf537b-c783-11e6-f6b9-7ea7909c64b9",
"product_id": "188a87aa-06fe-11e4-a0f5-b8ca3a64f8f4",
"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
"sequence": "0",
"handle": "mofo",
"sku": "10006",
"name": "mofo",
"quantity": -1,
"price": 200,
"cost": 100,
"price_set": 1,
"discount": 0,
"loyalty_value": 23,
"tax": 30,
"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
"tax_name": "GST",
"tax_rate": 0.15,
"tax_total": -30,
"price_total": -200,
"display_retail_price_tax_inclusive": "1",
"status": "CONFIRMED",
"attributes": [
{
"name": "is_return",
"value": "1"
}
]
},
{
"id": "06bf537b-c783-11e6-f6b9-7ea7909d949a",
"product_id": "188a87aa-06fe-11e4-a0f5-b8ca3a64f8f4",
"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
"sequence": "0",
"handle": "mofo",
"sku": "10006",
"name": "mofo",
"quantity": -1,
"price": 0,
"cost": 100,
"price_set": 1,
"discount": 0,
"loyalty_value": 0,
"tax": 0,
"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
"tax_name": "GST",
"tax_rate": 0.15,
"tax_total": 0,
"price_total": 0,
"display_retail_price_tax_inclusive": "1",
"status": "CONFIRMED",
"attributes": [
{
"name": "is_return",
"value": "1"
}
]
}
],
"totals": {
"total_tax": -30,
"total_price": -200,
"total_payment": -230,
"total_to_pay": 0
},
"register_sale_payments": [
{
"id": "06bf537b-c783-11e6-f6b9-7eab8f8ed241",
"payment_type_id": "1",
"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
"retailer_payment_type_id": "b1e1d70e-f019-11e3-a0f5-b8ca3a64f8f4",
"name": "Cash",
"label": "Cash",
"payment_date": "2016-09-19T20:28:03Z",
"amount": -230
}
],
"taxes": [
{
"id": "b1dfed8b-f019-11e3-a0f5-b8ca3a64f8f4",
"tax": -30,
"name": "GST",
"rate": 0.15
}
]
}
}
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 just the value of the returned item.
- It is possible to create multiple returns against a single sale.
Updated 5 months ago