This API allows you to store a new sale into the system. It is designed to receive complete sales that have been generated from a POS system, web selling screen, eCommerce systems or other sources. This is one of the larger and more complex APIs to understand, so we suggest you start by reading some examples.
Swagger DefinitionGoto: eLink Home | Product Modifiers (coffee)
Input Arguments
SalesHeader:
| Arg# | Binary | Description |
| 8 | 's' | Required. Constant 'retailmax.elink.sale.create' |
| 100 | 'E' | Optional. Sale Id number. If provided, must be unique. This field contains the unique server sale id to be used. Clients should generally not provide this value as several additional undocumented rules exist. If provided, must not be zero; zero is taken as no value provided. |
| 101 | 'y' | Optional, highly recommended. Completion Date/Time of the sale. If not supplied the server will insert the current date/time. If you are storing sales for later transmission and there is a chance the date will change between the sale being processed and uploaded via eLink, then this field must be provided as it is required for tax purposes. Acceptable date formats |
| 103 | 's' | Total value of sale, including all taxes. This value should equal f104 + f105 + f106 + f107 |
| 104 | 's' | Total value of sale, excluding all taxes |
| 105 | 's' | Total of tax #1 (GST in New Zealand, Australia, Zimbabwe. MwSt in Germany. VAT in United Kingdom) |
| 106 | 's' | Total of tax #2 |
| 107 | 's' | Total of tax #3 |
| 108 | 'E' | Optional, recommended. Phase of sale (see Reference List) Clients may only inject phases, 1=complete, 200=pending, 10000=void (store for audit) |
| 109 | 'y' | Optional, recommended. Start Date/Time of the sale. If not supplied the server will insert the completed date/time. If you are storing sales for later transmission and there is a chance the date will change between the sale being processed and uploaded via eLink, then this field must be provided as it is required for tax purposes. |
| 115 | 'E' | Teller or staff member id that processed this sale. |
| 117 | 'E' or 's' |
Customer id that made this sale. These ids are selected
from a known list of customers and will positive integers. Zero means unknown customer or value not set.
It is acceptable for distributed environments to use pending customer registrations and supply the TXKC value in this field. For example a newly defined customer record may be stored as "-6,Rs521UDEHAp1560|sq21" where this value is made from the negative Cid value (-6) and TXKC value seperated by a comma. Developers should be aware that this second form is ideally quite rare and should not be used widely. |
| 120 | 's' | Optional. Sale total. Total value of sale. If not supplied the server will insert the total of the salelines. If provided, it must be correct otherwise the server will reject the sale and not load it. This is the total of F205 (total price including taxes) fields from Saleline APPT packets |
| 122 | 'E' | System Specific identification code. |
| 123 | 'E' | System Specific unique sale number. Must be unique for every f122. Must be in the range >0 and < 2^31 |
| 125 | 'E' | Location id of the store that processed this sale. |
| 130 | 's' | External Sale Id. This field allows clients to specify a unique sale indentification string (maximum 32 bytes for maximum system reliability). |
| 131 | 'E' |
Sales Type information. Provides details about the type of sale being
uploaded which is often used for reporting purposes. Commonly seen values are
0. Normal sale created at a checkout 2. Web Site Sale. Sale originated from a CUSTOMER facing website. 4. Wholesale flag. Sale is a wholesale sale, not a standard retail sale. Full list of acceptable codes |
| 133 | 's' | Comments on this sale. Text only, comments DO NOT convey commands to the POS system. |
| 134 | 's' | Fly-Buys number |
| 135 | 'E' | Fly-Buys capture source. A coded number to indicate how f134 was captured. Possible values are 1=Retrieved from DPS EFTpos termainl, 2=Manual entered, 3=Copied from previous known source, ie anything that is already electronically known. 4=Barcode scanned |
| 136 | 's' | Tax registration number, such as GST number in New Zealand, ABN in Australia or VAT# in the United Kingdom. |
| 137 | 's' | Tax invoice number, or other legal sale #. This is the number shown to customers, while f100 are primarily internal numbers. If this field is not supplied, f100 is used as the external invoice number where required |
| 138 | 'E' | Charge account #. Where a customer/sale is being placed on a charge account, this field contains the account number to charge |
| 139 | 's' | Sale Physical Key |
| 144 | 's' | Meetu4 Shopper Id Card Number |
| 145 | 'E' | Meetu4 Shopper Id Card Number capture source |
| 146 | 'E' | Meetu4 Benchmark flags. Bitmask 1=send to Benchmark |
| 147 | 's' | Sale Tax control. Used to set specific tax handling features such as tax exempt. |
| 148 | 'E' | Target delivery country number. Where delivery of items is known to be an external country this field contains the country items are actually delivered too. |
| 149 | 'E' | Stock location number. Location where stock is to be extracted from if not the same as sales reporting location |
| 151 | 's' | (Advanced) Status change. Sets the name of a machine or bucket to be called when this sale is altered. Primarily this allows external applications loading sales to be advised when their sales are changed. eg. Web sales send status messages back to the source website as they are accepted/picked/completed. |
Dynamic Fields - Used on active salesThese values are available only while a sale is being actively processed using PosGreen. They exist to allow customer facing display units to interact and alter the current sale under the customers control. | ||
| 600 | 's' | Meetu4 reference URL. Includes host part. For example HTTP://MEETU4.ORG/$C100T1K0 |
| 601 | 'E' | Sale will print indicator. Used on active sales to indicate if a receipt will be printed or not. Has no meaning once a sale is complete. |
| 700 | 's' | Company Name or trading name, as would be shown to customers. This may not be the legal name of the retailer. |
| 701 | 's' | Receipt Header Lines. May be repeated several times to have multiple lines |
| 702 | 's' | Receipt Footer Lines. May be repeated several times to have multiple lines |
| 720 | 's' | Automatic Email Receipt requested. This field contains the address to send an email receipt to. |
| 721 | 's' | Remaining balance for Layby/Layaway sales |
Salelines can be added using an APPT subpacket with the following contents. Complete description of salelines Saleline Object or older structure APPT 21,1
| Arg# | Binary | Description |
| 2 | 'E' | Required. Constant '1' |
| 3 | 'E' | Required. Constant '21' |
| 200 | 'E' |
Required. Product id for the product being sold.
If this saleline is a modifier (rare) this field contains the Modifier id# |
| 201 | 'E' | NYI. Product variant id for the product being sold |
| 202 | 'E' | Quantity of product being sold. If not specified the value is assumed to be 1 (one). The quantity field is an integer (not a fractional number) in the measurement units of the product. Most items are unit based (a bar of chocolate), but others are weight or volume based ("flour"). If the item is measured in grams, then this field contains the number of grams. Use caution, as prices are typically in a different measurement, such as $ per Kilogram. |
| 203 | 'E' | Pidflag for the product being sold, which indicates the type of product id in f200. All normal products (those listed in retailmax.elink.products) use PidFlag=0, which is the default if not supplied. A value of "5" is used for Product Modifiers. |
| 205 | 's' | Required. Total price including all taxes where possible. |
| 206 | 'E' | Optional line sequence (ordinal position). If supplied, must be a positive integer. |
| 303 | 's' | Total value of line, including all taxes. This value should equal f304 + f305 + f306 + f307. If a sale contains a mix of taxable and non-taxable items, these fields must be present on all packets. |
| 304 | 's' | Total value of line, excluding all taxes |
| 305 | 's' | Total of tax #1 (GST in New Zealand, Australia, Zimbabwe. MwSt in Germany. VAT in United Kingdom) |
| 306 | 's' | Total of tax #2 |
| 307 | 's' | Total of tax #3 |
| 308 | 's' | Tax Control information |
| 320 | 's' | Optional. Unit price of item used for price calculations. |
| 400 | 'E' | Optional. Fuel Dispenser used for this item. |
| 401 | 's' | Optional. Serial Number of item. The quantity of this line is expected to be "1" as only one serial number can be stored per line |
| 410 | 'E' | Optional/Rare. Picked by Teller Id. (Not typically supplied when storing sales as servers allocate these values as items processed) |
| 411 | 'E' | Optional/Rare. Picked Qty. (Not typically supplied when storing sales as servers allocate these values as items processed) |
| 412 | 's' | Optional/Rare. Picked total price. (Not typically supplied when storing sales as servers allocate these values as items processed) |
Payments can be added using an APPT subpacket with the following contents. Complete description of payments APPT 21,2
| Arg# | Binary | Description |
| 2 | 'E' | Required. Constant '2' |
| 3 | 'E' | Required. Constant '21' |
| 200 | 'E' | Required. Payment Type code. |
| 201 | 's' | Required. Amount of the payment. This should be the actual amount involved, not rounded or adjusted. |
| 214 | 's' | External payment provider reference number. Where the payment was provided by external parties, this field contains a reference to that party. |
Physical delivery information can be added with an APPT 21,401. You do not need to store any linking information in fields f100-f119 as these will be added automatically.
If a sale is transmitted with a unique value in SalesHeader.f100 or SalesHeader.f130 that is already know by the server, the sale will not be stored a second time, but the server will return confirmation, like a new sale, not an error. This is explicitly to allow clients to transmit sales multiple times with safety.
If a sale transmits any of the SaleHeader.103, 104, 105, 106, 107 fields (relating to tax breakdown in the sale) it must transmit all the fields.
See also: The following definitions, which defines the underlying database storage written by this bucket: Sales Table | SaleLines Table | Payments Table
Output Fields
On success a QDNE response packet is returned. The following fields may be returned also.
You are explicitly allow to submit the same sale information multiple times and this API will only load the first time it receives the sale. This allows very simple clients to simply retransmit sales multiple times over a period of time rather than attempting retransmit logic. You are highly recommended to implement full end to end error checking, even if you transmit multiple times. For this retransmission safety to work, your API calls must include a unique F130/ExternalId value.
| Field | Datatype | Description |
| f100 | Number | The f100 Sale Id assigned to this sale |
| f101 | Number | A number indicating if the server already knew of this sale. While the value of the number has meaning to the server, clients should take any value 1 or higher as indication that the server already knew of the sale, a value of zero, or no value, indicates the sale was loaded now. |
| f510 | String | An information message that should be displayed to the user. This is not a simple confirmation message rather it contains less frequently occurring messages. |
Product Modifiers
Product modifiers are additional attributes connected to a saleline describing exact specifications. These are commonly seen when selling something such as coffee. A "Flat White" (product) can have many variations, such as number of sugar, type of milk, blend of coffee, topping plus many others. These additional attributes are sold/described by adding modifier salelines. Modifiers are not free form attributes, but describe a fixed addition or option applied to a product. Milk, for example, can only be selected from an available list of milks.
Product salelines can have any number of modifiers. Each modifier is listed immediately after the product being sold, and
has f203=5.
Examples
These examples are generally shown using XML for documentation purposes, you can also upload using JSON and other formats
Minimum sale example using named format. Sends a sale of one unit of product id #77, for a total price of $1. Paid in cash. This example is for demonstration purposes only, clients should provide more information than this for real sales.
<dati> <f8>retailmax.elink.sale.create</f8> <LINE> <Pid>77</Pid> <Qty>1</Qty> <TotalPrice>1.00</TotalPrice> </LINE> <PAYM> <Code>1</Code> <Amount>1.00</Amount> </PAYM> </dati>
Minimum sale example using older style numeric format. Sends a sale of one unit of product id #77, for a total price of $1. Paid in cash. This example is for demonstration purposes only, clients should provide more information than this for real sales.
<dati> <f8>retailmax.elink.sale.create</f8> <APPT> <f2>1</f2> <f3>21</f3> <f200>77</f200> <f202>1</f202> <f205>1.00</f205> </APPT> <APPT> <f2>2</f2> <f3>21</f3> <f200>1</f200> <f201>1.00</f201> </APPT> </dati>
Sale of two items at 2-Jan-2011 14:32:22. One for 15.00 with a serial number, the other for 1.3 Kg of flour, measured in grams. The client has assiged unique number "abc-123' to this sale.
<dati> <f8>retailmax.elink.sale.create</f8> <f130>ABC-123</f130> <f101_y>2011|01|02|14|32|22</f101_y> <APPT> <f2>1</f2> <f3>21</f3> <f200>43</f200> <f202>1</f202> <f205>15.00</f205> <f401>XY-41434B</f401> </APPT> <APPT> <f2>1</f2> <f3>21</f3> <f200>47</f200> <f202>1300</f202> <f205>6.50</f205> </APPT> <APPT> <f2>2</f2> <f3>21</f3> <f200>1</f200> <f201>21.50</f201> </APPT> </dati>
Sale of one item, with one modifier, which causes two salelines to be transmitted
<dati> <f8>retailmax.elink.sale.create</f8> <f130>ABC-123</f130> <f101_y>2011|01|02|14|32|22</f101_y> <APPT> <f2>1</f2> <f3>21</f3> <f200>43</f200> <f202>1</f202> <f203>0</f203> // Note Product flag set (optional) <f205>5.50</f205> </APPT> <APPT> <f2>1</f2> <f3>21</f3> <f200>4</f200> <f202>1</f202> <f203>5</f203> // Note Modifier flag set (required) </APPT> </dati>