Sales 101

Sales can be created by making a POST request to the /api/register_sales endpoint. This tutorial focuses on the payloads that can be used to create sales.

Minimal payload

Here's a minimal payload which can be POSTed to /api/register_sales to create a valid sale:

{
	"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
	"user_id": "b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4",
	"status": "SAVED",
	"register_sale_products": [{
		"product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
		"quantity": 1,
		"price": 12,
		"tax": 1.8,
		"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4"
	}]
}

Full payload with explanation

Following is a payload with all attributes that can be used to create a sale.

{
	"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
	"customer_id": "06e35f89-3783-11e6-ec7e-13193f7bd2ed",
	"user_id": "b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4",
	"sale_date": "2016-05-05 23:35:34",
	"note": "",
	"status": "CLOSED",
	"short_code": "mlzs94",
	"invoice_number": "MR-1484-NZ",
	"invoice_sequence": 1484,
	"register_sale_products": [{
		"product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
		"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
		"sequence": "0",
		"quantity": 1,
		"price": 22,
		"cost": 20,
		"price_set": 0,
		"discount": 0,
		"loyalty_value": 0,
		"tax": 3.3,
		"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
		"status": "CONFIRMED"
	}],
	"register_sale_payments": [{
		"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
		"retailer_payment_type_id": "b1e1d70e-f019-11e3-a0f5-b8ca3a64f8f4",
		"payment_date": "2016-05-05 23:35:34",
		"amount": 25.3
	}]
}

Definitions

The sale object

Attribute	Sample Value	Req/Opt	Description
`register_id`	`"b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4"`	required	Valid `id` of register to assign the sale to.
`customer_id`	`"06e35f89-3783-11e6-ec7e-13193f7bd2ed"`	optional	Valid `id` of the customer associated with the sale.
`user_id`	`"b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4"`	required	Valid `id` of a Lightspeed Retail (X-Series) user associated with the sale.
`sale_date`	`"2016-05-05 23:35:34"`	optional	by default current time will be assigned
`note`	`""`	optional	a note to be attached to the sale
`status`	`"CLOSED"`	required	One of: `SAVED`, `CLOSED`, `ONACCOUNT`, `LAYBY`, `ONACCOUNT_CLOSED`, `LAYBY_CLOSED`. More about sale statuses here.

`short_code`	`"mlzs94"`	optional	used for loyalty claiming, can be overwritten but must be unique.
`invoice_number`	`"MR-1484-NZ"`	optional	invoice number, if omitted one will be assigned by Lightspeed Retail (X-Series).
`invoice_sequence`	`1484`	optional	Numeric part of the invoice number.
`register_sale_products`	`[]`		An array of line items - definition of attributes in a table below. When updating a sale all existing products need to be included in the payload or they will be deleted.
`register_sale_payments`	`[]`		An array of payments - definition of attributes in a table below.

The register sale product object

Attribute	Sample Value	Req/Opt	Description
`product_id`	`"b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4"`	required	Lightspeed Retail (X-Series) product `id`
`register_id`	`"b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4"`	optional	A line item can be added on a different register than the sale was initially created.
`sequence`	`0`	optional	Order of the line item in the sale, safe to ignore.
`quantity`	`1`	required	Product quantity
`price`	`22`	required	Unit price, tax exclusive
`cost`	`20`	optional	Cost to be used for margin calculations
`price_set`	`0`	optional	Boolean value describing if sale was modified manually. Setting this to `1` will prevent price recalculation in the sell screen.
`discount`	`0`	optional	If the price was set manually, discount can be declared here for reporting.
`loyalty_value`	`2.0`	optional	the value by which customer's loyalty balance should be increased.
`tax`	`3.3`	required	Tax value
`tax_id`	`"b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4"`	required	Tax id as retrieved from `/api/2.0/taxes`.
`status`	`"SAVED"`	optional	CONFIRMED is the only meaningful, non-default option. Makes it impossible to remove product from the sale.

The register sale payment object

Attribute	Sample Value	Req/Opt	Description
`register_id`	`"b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4"`	optional	a payment can also be accepted in a sale different than the sale originate from
`retailer_payment_type_id`	`"b1e1d70e-f019-11e3-a0f5-b8ca3a64f8f4"`	required	Payment type id - that's the `id` of payment types retrieved from `/api/payment_types`
`payment_date`	`"2016-05-05 23:35:34"`	optional	By default current time will be assigned
`amount`	`25.3`	required	Payment amount

Taxes

The tax amount and tax_id should always be sent to /api/register_sales.

You can retrieve the relevant tax_id from /api/2.0/taxes.

Note: ALL retailers have a special tax with the name "No Tax", which represents "No Tax".

To post a tax-free sale, please fill tax_id field using the id of the tax named "name": "No Tax", along with a value of zero: "tax": 0.

Gotchas

An incorrect payload will not cause an error when posted to the /api/register_sales endpoint. Instead, an empty sale, with no products and payments will be created and the server will respond with 200 OK.
The sale should never be posted with OPEN status. That status is reserved for the client-side applications and should never make it to the server.