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_items to register_sale_products.

⚠️ DEPRECATION NOTICE
The status field in the sale object will be deprecated. Please migrate to using sale state and register_sale_attributes fields. 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_date attribute is optional. If not supplied, the current date/time will be used.

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",
 	"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 state of the sale should be changed to closed.

Voiding a sale

This simply requires changing the state of the sale to voided.

WARNING: Once the state 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