Introduction

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

AttributeSample ValueReq/OptDescription
register_id"b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4"requiredValid id of register to assign the sale to.
customer_id"06e35f89-3783-11e6-ec7e-13193f7bd2ed"optionalValid id of the customer associated with the sale.
user_id"b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4"requiredValid id of a Lightspeed Retail (X-Series) user associated with the sale.
sale_date"2016-05-05 23:35:34"optionalby default current time will be assigned
note""optionala note to be attached to the sale
status"CLOSED"requiredOne of: SAVED, CLOSED, ON_ACCOUNT, LAYBY, ON_ACCOUNT_CLOSED, LAYBY_CLOSED. More about sale statuses here.
short_code"mlzs94"optionalused for loyalty claiming, can be overwritten but must be unique.
invoice_number"MR-1484-NZ"optionalinvoice number, if omitted one will be assigned by Lightspeed Retail (X-Series).
invoice_sequence1484optionalNumeric 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

AttributeSample ValueReq/OptDescription
product_id"b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4"requiredLightspeed Retail (X-Series) product id
register_id"b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4"optionalA line item can be added on a different register than the sale was initially created.
sequence0optionalOrder of the line item in the sale, safe to ignore.
quantity1requiredProduct quantity
price22requiredUnit price, tax exclusive
cost20optionalCost to be used for margin calculations
price_set0optionalBoolean value describing if sale was modified manually. Setting this to 1 will prevent price recalculation in the sell screen.
discount0optionalIf the price was set manually, discount can be declared here for reporting.
loyalty_value2.0optionalthe value by which customer's loyalty balance should be increased.
tax3.3requiredTax value
tax_id"b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4"requiredTax id as retrieved from /api/2.0/taxes.
status"SAVED"optionalCONFIRMED is the only meaningful, non-default option. Makes it impossible to remove product from the sale.

The register sale payment object

AttributeSample ValueReq/OptDescription
register_id"b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4"optionala payment can also be accepted in a sale different than the sale originate from
retailer_payment_type_id"b1e1d70e-f019-11e3-a0f5-b8ca3a64f8f4"requiredPayment type id - that's the id of payment types retrieved from /api/payment_types
payment_date"2016-05-05 23:35:34"optionalBy default current time will be assigned
amount25.3requiredPayment 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.

Did this page help you?