Editing Sales
Editing Sales
To edit a sale, a POST request with the appropriate payload should be posted to the API 0.9
/api/register_sales endpoint.
WARNING: The current sales endpoint (
/api/register_sales) behaves a bit differently than other POST endpoints. Where in the majority of other endpoints it is possible to submit partial payloads, the sale has to be submitted with all the attributes of an existing sale.
E.g. if a sale is submitted without the line items (register_sale_products) which existed on it previously, they will be deleted and replaced with whatever is posted.
WARNING: It's worth noticing that there are a few important differences in payload attribute names between API 0.9 and API 2.0. So, if you get the sale data from API 2.0 and using it compose a payload to post back to API 0.9 you will have to, for example, rename
line_itemstoregister_sale_products.
⚠️ DEPRECATION NOTICE
Thestatusfield in the sale object will be deprecated. Please migrate to using salestateandregister_sale_attributesfields. See States and attributes page for more information.
Adding line items
To add a new line item to the sale a new item should be added to the register_sale_products array in the sale payload. Below is an example of the minimal set of attributes that should be included:
{
"product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
"quantity": 1,
"price": 22,
"tax": 3.3,
"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4"
}More details on what other attributes can be used can be found here.
So, in the case of a parked sale with no previous payments on it, the payload should look like this:
{
"id": "a604d16b-a999-a82b-11e7-2ddc0a37c22b",
"source": "USER",
"source_id": "",
"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
"market_id": "1",
"customer_id": "b1cabb53-f019-11e3-a0f5-b8ca3a64f8f4",
"user_id": "b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4",
"user_name": "[email protected]",
"sale_date": "2017-04-30 22:29:00",
"created_at": "2017-04-30 22:29:00",
"updated_at": "2017-04-30 22:29:00",
"total_price": 12,
"total_cost": 8.73,
"total_tax": 1.8,
"tax_name": "GST",
"note": "",
"status": "SAVED",
"state": "parked",
"register_sale_attributes": [],
"short_code": "aidgvq",
"invoice_number": "MR-1704-NZ",
"accounts_transaction_id": "",
"return_for": "",
"register_sale_products": [{
"id": "a604d16b-a999-963a-11e7-2df456273584",
"product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
"sequence": "0",
"handle": "tshirt",
"sku": "tshirt-white",
"name": "T-shirt",
"quantity": 1,
"price": 12,
"cost": 8.73,
"price_set": 0,
"discount": 0,
"loyalty_value": 1.38,
"tax": 1.8,
"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
"tax_name": "GST",
"tax_rate": 0.15,
"tax_total": 1.8,
"price_total": 12,
"display_retail_price_tax_inclusive": "1",
"status": "SAVED",
"attributes": [{
"name": "line_note",
"value": ""
}]
},
{
"product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
"quantity": 1,
"price": 12,
"tax": 1.8,
"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4"
}
]
}Adding payments
To add a payment to a sale the following object should be added to the register_sale_payments array in the payload:
{
"retailer_payment_type_id": "b1e1d70e-f019-11e3-a0f5-b8ca3a64f8f4",
"payment_date": "2016-09-19T20:28:03Z",
"amount": -230.12
}NOTE:
- The
payment_dateattribute is optional. If not supplied, the current date/time will be used.- The
retailer_payment_type_idattribute is theidof a valid payment type that can be retrieved from/api/payment_typesor/api/2.0/payment_typesendpoints.
In the case of a sale where some payments have been added previously, the sale payload to be posted should look like that:
{
"id": "a604d16b-a999-9212-11e7-2ae82f545149",
"source": "USER",
"source_id": "",
"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
"market_id": "1",
"customer_id": "dc85058a-a683-11e4-ef46-e256d3551c9d",
"user_id": "b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4",
"user_name": "[email protected]",
"sale_date": "2017-04-27 04:14:33",
"created_at": "2017-04-27 04:14:39",
"updated_at": "2017-04-27 04:14:39",
"total_price": 1200,
"total_cost": 205.52,
"total_tax": 180,
"tax_name": "GST",
"note": "",
"status": "ONACCOUNT",
"state": "pending",
"register_sale_attributes": ["onaccount"],
"short_code": "nydtpj",
"invoice_number": "MR-1701-NZ",
"accounts_transaction_id": "",
"return_for": "",
"register_sale_products": [{
"id": "a604d16b-a999-9212-11e7-2affc316bc8c",
"product_id": "b8ca3a65-0183-11e4-fbb5-6ba391393b6e",
"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
"sequence": "0",
"handle": "MoustachePotion1",
"sku": "10012",
"name": "Moustache Potion",
"quantity": 1,
"price": 1200,
"cost": 205.52,
"price_set": 0,
"discount": -115,
"loyalty_value": 138,
"tax": 180,
"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
"tax_name": "GST",
"tax_rate": 0.15,
"tax_total": 180,
"price_total": 1200,
"display_retail_price_tax_inclusive": "1",
"status": "CONFIRMED",
"attributes": [{
"name": "line_note",
"value": ""
}]
}],
"register_sale_payments": [{
"id": "a604d16b-a999-a251-11e7-2afff8a8a128",
"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": "2017-04-27 04:14:13",
"amount": 200
},
{
"retailer_payment_type_id": "b1e1d70e-f019-11e3-a0f5-b8ca3a64f8f4",
"payment_date": "2017-04-27 04:14:13",
"amount": 400
}],
}Changing the state
Previously, this was done by changing the value of the status field of the sale. Now it is done by changing the value of the state field of the sale. As with the previous operations, a full sale payload should be used for this request.
The 2 most common use-cases for changing the state are completing or voiding a sale. They are worth mentioning separately as they usually require a differently prepared payload.
Completing a sale
When this is done, there are usually 2 things that should happen in the payload:
- A payment should be added to pay off the outstanding balance of the sale. This can be done as described above.
- The
stateof the sale should be changed toclosed.
Voiding a sale
This simply requires changing the state of the sale to voided.
WARNING: Once the state of a sale is set to
voidedit shouldn't be changed to anything else. Doing so may result in corrupting inventory and payment data.
Creating a return
Creating returns is described in a separate article here: Sale returns
Updated about 21 hours ago
