Line Item Display

Home/Developers / Line Item DisplayQuick Links

Line Item Display Certification Information

To complete certification for Line Item Display the following transitions must be validated:

  1. CreateTransaction must be used to complete the order if the payment will be accepted through the CED. Once a TransportKey is obtained from the CreateTransaction function, performing an InitiateTransaction will automatically end the line item display and begin the checkout process on the CED.
  2. EndOrder should only be used when payment is accepted outside of the Genius CED. For example, if a consumer pays with cash or check.
  3. Cancel should only be used if the order is not completed and payment is not collected. For example, the consumer chooses to not make a purchase, or if the Point of Sale is going to put the order on hold.

Line Item Display Overview

This documentation serves as a reference guide for Point of Sale developers looking to display line item level data on the Genius CED. The parameters for each action are strict. If you supply a parameter which cannot be handled by that particular action, you will receive an error message in an HTTP 400 Bad Request response.

Key points are as follows:

  •  Communication requests between the two systems are made using the HTTP and must follow the RFC 3986 specification.
  •  All HTTP / HTTPS requests must be URI encoded.
  •  HTTP / HTTPS requests made to the CED are case sensitive.
  •  If the format is not specified or invalid, an XML response will be returned with error details.

Line Item Display Flow

1 Start Transaction Notify the CED of a new transaction and change the screen to display order details.
2 Display Items a. Send item details to display on the CED screen.
b. Send discount & coupon information to show on the CED screen.
3 End Transaction Optional If the payment collection occurs outside of the Genius CED (i.e. Cash or Check) then the POS can alert the CED to clear the screen. If the payment is collected through the CED then this step is not needed as the regular 'Initiate Transaction' call to collect payment will clear the screen and process the payment.

Request / Response

Request Use GET to send the item details to the CED. The device will display each request to the customer and will respond back to the POS with the result. The Point of Sale will keep the port open to the device and wait for the GET request to complete. The GET response will contain an XML, JSON or JSONP packet.
Response When the transaction is completed, the device will send the transaction results back to the Point of Sale so it can be parsed out, stored and used at a later time if necessary.

1 Start Transaction

StartOrder Method to initiate the line item display screen and the start of the transaction.

Sample StartOrder request
http://[CED-IP-Address]:8080/v1/pos?Action=StartOrder&Order=1000&Format=XML
Additional Connection Methods

Request Parameters

Name Type Required Size Description
Action String X 1-16 StartOrder- Method to start an order on the line display screen.
Order String X 1-8 The order or invoice number associated with the transaction. This field must match the order value sent in the StartOrder call in step 1.
Format String X 1-5 The format that the CED should respond in. Possible values are:
  • XML
  • JSON

Response Parameters

Name Type Description
Status String The status of the start order request. Possible values:
  • Success
  • Failed
  • Denied
ResponseMessage String Message for Failed or Denied transactions. This field can contain any string and should not be treated as an enumeration. (Example: 'Can't connect, another order already in progress').
AdditionalParameters Object Placeholder for any necessary future fields.

Examples

XML response example:

<?xml version="1.0" encoding="utf-8"?>
<OrderResult>
    <Status>Success</Status>
    <ResponseMessage/>
    <AdditionalParameters/>
</OrderResult>
					

JSON response example:

{
  "Status": "Success",
  "ResponseMessage": "",
  "AdditionalParameters": {
    
  }
}
					

2 Display Items

Supported Functions for Adding, updating and removing items

1 Add Item Add an item to the line display screen and display updated data for tax and total amounts.
2 Discount Item Add a discount line item to the display screen and display updated data for tax and total amounts.
3 Delete Item Delete an item from the items list.
4 Delete All Items Delete all items from the items list.
5 Update Item Update an existing item.
6 Update Total Update the order totals without adding or removing items.

1 Add Item

Method to add an item to the line display screen and display updated data for tax and total amounts.

Sample AddItem request
http://[CED-IP-Address]:8080/v1/pos?Action=AddItem&Order=1000&Type=Sku&TypeValue=xxx&UPC=xxx&Quantity=xxx&Description=xxx&Amount=xxx&TaxAmount=xxx&OrderTotal=xxx&OrderTax=xxx&Category=None&Format=xxx
Additional Connection Methods

Request Parameters

Name Type Required Size Description
Action String X 1-16 AddItem - Method to add an item to the line display screen and display updated data for tax and total amounts.
Order String X 1-8 The order or invoice number associated with the transaction. This field must match the order value sent in the StartOrder call in step 1.
ItemID String optional 1-8 The unique (per transaction) identifier for the item. This can be used later to perform actions on the item like deleting or updating it. If this field is left blank, the CED will generate an ItemID and will return it in the response.
Type String X 1-8 Custom type of item tracking unit. Currently supported values:
  • Sku - for items that have a SKU associated with them. Important for usage with promotions, offers and rewards that might be run by a service provider like LevelUp.
  • Misc - for custom items that do not have a SKU like services.
TypeValue String X 1-32 Value of the data that is used to track the item type. For an item of type Sku this would be the Sku number. For Misc types this would be a service code or any other identifier.
UPC String optional 1-32 Raw UPC code from the item's barcode. This is important to include to take advantage of any promotions, offers and rewards that might be run by a service provider like LevelUp.
Quantity String X 1-3 The number of the same item if scanned at the same time. Each item can also be sent in separately, one per line, if preferred.
Description String X 1-35 The item description that will appear to the customer on the CED screen.
Amount String X 1-9 The sale price of the individual item. This value will be multiplied by the quantity passed in.
TaxAmount String X 1-9 The amount of tax on this item. The tax amount is not multiplied by the quantity.
OrderTotal String X 1-9 Updates the order total amount displayed on the CED screen.
OrderTax String X 1-9 Updates the order tax amount displayed on the CED screen. This does not get added to the OrderTotal field and is used for display purposes only.
Category String X 1-8 Type of item being added. This will be used to validate items eligible for EBT and Petroleum transactions. Supported values (case sensitive):
  • None - used for standard items.
  • Ebt items that are eligible for EBT transactions.
  • Fuel items that are eligible for Petroleum/Fuel transactions.
DisplayOverride String optional 0-35 Set the full display line text. This will override the auto-generated display that the CED shows by default. You can pass these modifiers to change the text display:
  • [] wrap text inside the brackets to 'pull' the data to the right. This is useful when you want to line up the price on the right side of the screen.
  • _r() wrap any text that you would like to have appear in red in this tag. Some uses might be to show a refund, coupon or discount.
  • _w() (default) wrap any text that you would like to appear in this tag. Any text not wrapped in _r() will be treated as white text so the use of this tag should be rare.
DisplayCustomSubTotal String optional 0-35 Display a custom subtotal line item above the order total and order tax amount fields. You can use this field for subtotal display or any other custom display you may need.
Format String X 1-5 The format that the CED should respond in. Possible values are:
  • XML
  • JSON

Response Parameters

Name Type Description
Status String The result of request. Possible values:
  • Success
  • Failed
  • Denied
ResponseMessage String A message indicating why the transaction could not be processed if the status was Failed or Denied.
ItemID int The ItemID that was passed in the request. If there was no ItemID sent in, an ItemID will be generated by the CED and returned to the POS. The ItemID is needed for other functions like UpdateItem.
AdditionalParameters Object Placeholder for any necessary future fields.

Examples

XML response example:

<?xml version="1.0" encoding="utf-8"?>
<OrderResult>
    <Status>Success</Status>
    <ResponseMessage/>
    <ItemID>1</ItemID>
    <AdditionalParameters/>
</OrderResult>
					

JSON response example:

{
  "Status": "Success",
  "ResponseMessage": "",
  "ItemID": "1",
  "AdditionalParameters": {
    
  }
}
					

2 Discount Item

Method to add a discount line item to the display screen and display updated data for tax and total amounts. This will apply a negative value to the order. Note: If you delete the item associated with the discount, you must also delete the discount.

Sample DiscountItem request
http://[CED-IP-Address]:8080/v1/pos?Action=DiscountItem&Order=xxx&Type=Sku&TypeValue=xxx&UPC=xxx&Quantity=xxx&Description=xxx&Amount=xxx&TaxAmount=xxx&OrderTotal=xxx&OrderTax=xxx&Category=xxx&Format=xxx
Additional Connection Methods

Request Parameters

Name Type Required Size Description
Action String X 1-16 discountitem - Method to add an item to the line display screen and display updated data for tax and total amounts.
Order String X 1-8 The order or invoice number associated with the transaction. This field must match the order value sent in the StartOrder call in step 1.
ItemID String optional 1-8 The unique (per transaction) identifier for the item. This can be used later to perform actions on the item like deleting or updating it. If this field is left blank, the CED will generate an ItemID and will return it in the response.
TargetItemID String X 1-8 The unique (per transaction) identifier for the item being discounted. This should be the ItemID of another line item currently on the display.
Type String X 1-8 Custom type of item tracking unit. Currently supported values:
  • Sku - for items that have a SKU associated with them. Important for usage with promotions, offers and rewards that might be run by a service provider like LevelUp.
  • Misc - for custom items that do not have a SKU like services.
TypeValue String X 1-32 Value of the data that is used to track the item type. For an item of type Sku this would be the Sku number. For Misc types this would be a service code or any other identifier.
UPC String optional 1-32 Raw UPC code from the item's barcode. This is important to include to take advantage of any promotions, offers and rewards that might be run by a service provider like LevelUp.
Quantity String X 1-3 The number of the same item if scanned at the same time. Each item can also be sent in separately, one per line, if preferred.
Description String X 1-35 The item description that will appear to the customer on the CED screen.
Amount String X 1-9 The sale price of the individual item. This value will be multiplied by the quantity passed in.
TaxAmount String X 1-9 The amount of tax on this item. The tax amount is not multiplied by the quantity.
OrderTotal String X 1-9 Updates the order total amount displayed on the CED screen.
OrderTax String X 1-9 Updates the order tax amount displayed on the CED screen. This does not get added to the OrderTotal field and is used for display purposes only.
Category String X 1-8 Type of item being added. This will be used to validate items eligible for EBT and Petroleum transactions. Supported values (case sensitive):
  • None - used for standard items.
  • Ebt items that are eligible for EBT transactions.
  • Fuel items that are eligible for Petroleum/Fuel transactions.
DisplayOverride String optional 0-35 Set the full display line text. This will override the auto-generated display that the CED shows by default. You can pass these modifiers to change the text display:
  • [] wrap text inside the brackets to 'pull' the data to the right. This is useful when you want to line up the price on the right side of the screen.
  • _r() wrap any text that you would like to have appear in red in this tag. Some uses might be to show a refund, coupon or discount.
  • _w() (default) wrap any text that you would like to appear in this tag. Any text not wrapped in _r() will be treated as white text so the use of this tag should be rare.
DisplayCustomSubTotal String optional 0-35 Display a custom subtotal line item above the order total and order tax amount fields. You can use this field for subtotal display or any other custom display you may need.
Format String X 1-5 The format that the CED should respond in. Possible values are:
  • XML
  • JSON

Response Parameters

Name Type Description
Status String The result of request. Possible values:
  • Success
  • Failed
  • Denied
ResponseMessage String A message indicating why the transaction could not be processed if the status was Failed or Denied.
ItemID int The ItemID that was passed in the request. If there was no ItemID sent in, an ItemID will be generated by the CED and returned to the POS. The ItemID is needed for other functions like UpdateItem.
AdditionalParameters Object Placeholder for any necessary future fields.

Examples

XML response example:

<?xml version="1.0" encoding="utf-8"?>
<OrderResult>
    <Status>Success</Status>
    <ResponseMessage/>
    <ItemID>1</ItemID>
    <AdditionalParameters/>
</OrderResult>
					

JSON response example:

{
  "Status": "Success",
  "ResponseMessage": "",
  "ItemID": "1",
  "AdditionalParameters": {
    
  }
}
					

3 Delete Item

Method to delete an item from the items list.

Sample deleteitem request
http://[CED-IP-Address]:8080/v1/pos?Action=DeleteItem&Order=xxx&TargetItemID=xxx&OrderTotal=xxx&OrderTax=xxx&Format=xxx
Additional Connection Methods

Request Parameters

Name Type Required Size Description
Action String X 1-16 DeleteItem - Method to delete an item from the line display screen and display updated data for tax and total amounts.
Order String X 1-8 The order or invoice number associated with the transaction. This field must match the order value sent in the StartOrder call in step 1.
TargetItemID String X 1-8 The unique (per transaction) identifier for the item that is being deleted. This should be the ItemID of an existing line item currently on the display.
OrderTotal String X 1-9 Updates the order total amount displayed on the CED screen.
OrderTax String X 1-9 Updates the order tax amount displayed on the CED screen. This does not get added to the OrderTotal field and is used for display purposes only.
DisplayCustomSubTotal String optional 0-35 Display a custom subtotal line item above the order total and order tax amount fields. You can use this field for subtotal display or any other custom display you may need.
Format String X 1-5 The format that the CED should respond in. Possible values are:
  • XML
  • JSON

Response Parameters

Name Type Description
Status String The result of request. Possible values:
  • Success
  • Failed
  • Denied
ResponseMessage String A message indicating why the transaction could not be processed if the status was Failed or Denied.
AdditionalParameters Object Placeholder for any necessary future fields.

Examples

XML response example:

<?xml version="1.0" encoding="utf-8"?>
<OrderResult>
    <Status>Success</Status>
    <ResponseMessage/>
    <AdditionalParameters/>
</OrderResult>
					

JSON response example:

{
  "Status": "Success",
  "ResponseMessage": "",
  "AdditionalParameters": {
    
  }
}
					

4 Delete All Items

Method to delete all items from the items list.

Sample DeleteAllItems request
http://[CED-IP-Address]:8080/v1/pos?Action=DeleteAllItems&Order=xxx&RetainPaymentData=xxx&OrderTotal=xxx&OrderTax=xxx&DisplayCustomSubTotal=xxx&Format=xxx
Additional Connection Methods

Request Parameters

Name Type Required Size Description
Action String X 1-16 DeleteAllItems - Method to delete all items from the line display screen and display updated data for tax and total amounts.
Order String X 1-8 The order or invoice number associated with the transaction. This field must match the order value sent in the StartOrder call in step 1.
RetainPaymentData String X 4-5 A flag indicating whether the CED should retain any payment details already captured (e.g. card swipe, NFC tap, QR Code scan) when all the line items are removed. Possible values are:
  • false - payment data is removed along with the line items. This is the default if RetainPaymentData is omitted.
  • true -payment data is retained when the line items are removed.
OrderTotal String X 1-9 Updates the order total amount displayed on the CED screen.
OrderTax String X 1-9 Updates the order tax amount displayed on the CED screen. This does not get added to the OrderTotal field and is used for display purposes only.
DisplayCustomSubTotal String optional 0-35 Display a custom subtotal line item above the order total and order tax amount fields. You can use this field for subtotal display or any other custom display you may need.
Format String X 1-5 The format that the CED should respond in. Possible values are:
  • XML
  • JSON

Response Parameters

Name Type Description
Status String The result of request. Possible values:
  • Success
  • Failed
  • Denied
ResponseMessage String A message indicating why the transaction could not be processed if the status was Failed or Denied.
AdditionalParameters Object Placeholder for any necessary future fields.

Examples

XML response example:

<?xml version="1.0" encoding="utf-8"?>
<OrderResult>
    <Status>Success</Status>
    <ResponseMessage/>
    <AdditionalParameters/>
</OrderResult>
					

JSON response example:

{
  "Status": "Success",
  "ResponseMessage": "",
  "AdditionalParameters": {
    
  }
}
					
 

5 Update Item

Method to update an existing item.

Sample Update Item request
http://[CED-IP-Address]:8080/v1/pos?Action=UpdateItem&Order=xxx&TargetItemID=xxx&OrderTotal=xxx&OrderTax=xxx&Format=xxx
Additional Connection Methods

Request Parameters

Name Type Required Size Description
Action String X 1-16 updateitem - Method to update an item on the line display screen and display updated data for tax and total amounts.
Order String X 1-8 The order or invoice number associated with the transaction. This field must match the order value sent in the StartOrder call in step 1.
TargetItemID String X 1-8 The unique (per transaction) identifier for the item. This can be used later to perform actions on the item like deleting or updating it. If this field is left blank, the CED will generate an ItemID and will return it in the response.
Type String optional 1-8 Custom type of item tracking unit. Currently supported values:
  • Sku - for items that have a SKU associated with them. Important for usage with promotions, offers and rewards that might be run by a service provider like LevelUp.
  • updateitem - for custom items that do not have a SKU like services.
TypeValue String optional 1-32 Value of the data that is used to track the item type. For an item of type Sku this would be the Sku number. For Misc types this would be a service code or any other identifier.
UPC String optional 1-32 Raw UPC code from the item's barcode. This is important to include to take advantage of any promotions, offers and rewards that might be run by a service provider like LevelUp.
Quantity String optional 1-3 The number of the same item if scanned at the same time. Each item can also be sent in separately, one per line, if preferred.
Description String optional 1-35 The item description that will appear to the customer on the CED screen.
Amount String optional 1-9 The sale price of the individual item. This value will be multiplied by the quantity passed in.
TaxAmount String optional 1-9 The amount of tax on this item. The tax amount is not multiplied by the quantity.
OrderTotal String X 1-9 Updates the order total amount displayed on the CED screen.
OrderTax String X 1-9 Updates the order tax amount displayed on the CED screen. This does not get added to the OrderTotal field and is used for display purposes only.
Category String X 1-8 Type of item being added. This will be used to validate items eligible for EBT and Petroleum transactions. Supported values (case sensitive):
  • None - used for standard items.
  • Ebt items that are eligible for EBT transactions.
  • Fuel items that are eligible for Petroleum/Fuel transactions.
DisplayOverride String optional 0-35 Set the full display line text. This will override the auto-generated display that the CED shows by default. You can pass these modifiers to change the text display:
  • [] wrap text inside the brackets to 'pull' the data to the right. This is useful when you want to line up the price on the right side of the screen.
  • _r() wrap any text that you would like to have appear in red in this tag. Some uses might be to show a refund, coupon or discount.
  • _w() (default) wrap any text that you would like to appear in this tag. Any text not wrapped in _r() will be treated as white text so the use of this tag should be rare.
DisplayCustomSubTotal String optional 0-35 Display a custom subtotal line item above the order total and order tax amount fields. You can use this field for subtotal display or any other custom display you may need.
Format String X 1-5 The format that the CED should respond in. Possible values are:
  • XML
  • JSON

Response Parameters

Name Type Description
Status String The result of request. Possible values:
  • Success
  • Failed
  • Denied
ResponseMessage String A message indicating why the transaction could not be processed if the status was Failed or Denied.
ItemID int The ItemID that was passed in the request as the TargetItemID.
AdditionalParameters Object Placeholder for any necessary future fields.

Examples

XML response example:

<?xml version="1.0" encoding="utf-8"?>
<OrderResult>
    <Status>Success</Status>
    <ResponseMessage/>
    <ItemID>1</ItemID>
    <AdditionalParameters/>
</OrderResult>
					

JSON response example:

{
  "Status": "Success",
  "ResponseMessage": "",
  "ItemID": "1",
  "AdditionalParameters": {
    
  }
}
					
 

6 Update Total

Method to update the order totals without adding/removing items.

Sample Update Total request
http://[CED-IP-Address]:8080/v1/pos?Action=UpdateTotal&Order=xxx&OrderTotal=xxx&OrderTax=xxx&Format=xxx
Additional Connection Methods

Request Parameters

Name Type Required Size Description
Action String X 1-16 UpdateTotal - Method to update tax and total amounts.
Order String X 1-8 The order or invoice number associated with the transaction. This field must match the order value sent in the StartOrder call in step 1.
OrderTotal String X 1-9 Updates the order total amount displayed on the CED screen.
OrderTax String X 1-9 Updates the order tax amount displayed on the CED screen. This does not get added to the OrderTotal field and is used for display purposes only.
DisplayCustomSubTotal String optional 0-35 Display a custom subtotal line item above the order total and order tax amount fields. You can use this field for subtotal display or any other custom display you may need.
Format String X 1-5 The format that the CED should respond in. Possible values are:
  • XML
  • JSON

Response Parameters

Name Type Description
Status String The result of request. Possible values:
  • Success
  • Failed
  • Denied
ResponseMessage String A message indicating why the transaction could not be processed if the status was Failed or Denied.
AdditionalParameters Object Placeholder for any necessary future fields.

Examples

XML response example:

<?xml version="1.0" encoding="utf-8"?>
<OrderResult>
    <Status>Success</Status>
    <ResponseMessage/>
    <AdditionalParameters/>
</OrderResult>
					

JSON response example:

{
  "Status": "Success",
  "ResponseMessage": "",
  "AdditionalParameters": {
    
  }
}
					
 

4 Additional Functions

Get current order details and summaries

1 Order Summary Method to get the summary of the current order.

1 Order Summary

Method to get the summary of the current order.

Sample OrderSummary request
http://[CED-IP-Address]:8080/v1/pos?Action=OrderSummary&Order=xxx&Format=xxx
Additional Connection Methods

Request Parameters

Name Type Required Size Description
Action String X 1-10 OrderSummary - Method to retrieve the summary of the current order.
Order String X 1-8 The order or invoice number associated with the transaction. This field must match the order value sent in the StartOrder call in step 1.
Format String X 1-5 The format that the CED should respond in. Possible values are:
  • XML
  • JSON

Response Parameters

Name Type Description
Status String The result of request. Possible values:
  • Open
  • Failed
  • Denied
ResponseMessage String A message indicating why the transaction could not be processed if the status was Failed or Denied. This field can contain any string, and should not be treated as an enumeration.
Items Integer The quantity of items (not including discounts) showing on the screen.
Discounts Integer The quantity of discounts currently showing on the screen.
TotalAmount String The total amount value for the current order.
CustomSubTotal String The custom subtotal value for the current order.
TaxAmount String The tax amount value for the current order.
AdditionalParameters Object Placeholder for any necessary future fields.

Examples

XML response example:

<?xml version="1.0" encoding="utf-8"?>
<OrderResult>
    <Status>Open</Status>
    <ResponseMessage/>
    <Items>4</Items>
    <Discounts>0</Discounts>
    <TotalAmount>28.76</TotalAmount>
    <CustomSubTotal/>
    <TaxAmount>1.88</TaxAmount>
    <AdditionalParameters/>
</OrderResult>
					

JSON response example:

{
  "Status": "Open",
  "ResponseMessage": "",
  "Items": "4",
  "Discounts": "0",
  "TotalAmount": "28.76",
  "CustomSubTotal": "",
  "TaxAmount": "1.88",
  "AdditionalParameters": {
    
  }
}
					

3 End Transaction

Complete line item display and process payment

1 End Order Method to complete the line item display for transactions completed outside of the Genius CED.
 

1 End Order

Method to complete the line item display for transactions completed outside of the Genius CED.

Sample EndOrder request
http://[CED-IP-Address]:8080/v1/pos?Action=EndOrder&Order=xxxxxxxx&ExternalPaymentType=xxx&Format=xxx
Additional Connection Methods

Request Parameters

Name Type Required Size Description
Action String X 1-10 EndOrder - The end SKU request call..
Order String X 1-8 The order or invoice number associated with the transaction. This field must match the order value sent in the StartOrder call in step 1.
ExternalPaymentType String X 1-19 Type of tender used to collect the payment. Some possible values are:
  • Cash
  • Check
  • StoreCredit
  • Other
Format String X 1-5 The format that the CED should respond in. Possible values are:
  • XML
  • JSON

Response Parameters

Name Type Description
Status String The result of request. Possible values:
  • Success
  • Failed
  • Denied
ResponseMessage String A message indicating why the transaction could not be processed if the status was Failed or Denied, i.e. Can’t connect, order number does not match.
AdditionalParameters Object Placeholder for any necessary future fields.

Examples

XML response example:

<?xml version="1.0" encoding="utf-8"?>
<OrderResult>
    <Status>Success</Status>
    <ResponseMessage/>
    <AdditionalParameters/>
</OrderResult>
					

JSON response example:

{
  "Status": "Success",
  "ResponseMessage": "",
  "AdditionalParameters": {
    
  }
}
					
A changelog can be viewed here.