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 Vend 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, ON_ACCOUNT, LAYBY, ON_ACCOUNT_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 Vend.
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 Vend 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/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

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 me posted with OPEN status. That status is reserved for the client-side applications and should never make it to the server.