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 to register_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- The retailer_payment_type_id attribute is the id 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 or ONACCOUNT_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