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.\nE.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_items
toregister_sale_products
.
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 (SAVED
) 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",
"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_date
attribute is optional. If not supplied the current date/time will be used.\n- Theretailer_payment_type_id
attribute is theid
of a valid payment type that can be retrieved from/api/payment_types
or/api/2.0/payment_types
endpoints.
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",
"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 status
This is done, by changing the value of the status
attribute of the sale and, as with the previous operations, a full sale payload should be used for this request.
The 2 most common use-cases for changing the status is completing or voiding a sale. They are worth mentioning separately as they usually require differently prepared payload.
More about sale statuses here.
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
status
of the sale should be changed to one of:CLOSED
,LAYBY_CLOSED
orONACCOUNT_CLOSED
.
Voiding a sale
This simply requires changing the status of the sale to VOIDED
.
WARNING: Once the status of a sale is set to
VOIDED
it 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 6 months ago