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/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 with200 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.