Get a check
{basePath}/checks/{checkRef}
{basePath}/checks/929aacee2c6d42c78ae877e824c28eed00000431
API returns the requested check from the specified revenue center using the checkRef which can be found in the check status response once a check has been created at the POS or by using one of the other known query parameters with the GET Checks endpoint to retrieve the checkRef.
Request
- application/json
-
checkRef(required): string
Check identifier
-
Accept-Language: string
The Accept Language header identifies the language that is desired for the response.
-
Simphony-LocRef(required): string
The location identifier.
-
Simphony-OrgShortName(required): string
The organization identifier.
-
Simphony-RvcRef(required): integer
The revenue center identifier.
Response
- application/json
200 Response
object
-
checkNotifications:
array checkNotifications
Array of past notifications for the check.
-
comboMeals:
array comboMeals
Array of combo meal items. If there were no combo meal items on the check the returned array will be empty.
-
discounts:
array discounts
Array of discounts.
-
extensions:
array extensions
Array of extension detail.
-
header(required):
object CheckHeader
The check header contains information describing the overall check.
- menuItems: array menuItems
-
notificationOptions:
object CheckNotificationOptions
Integrator-provided options for notifications. Following NotificationOptions are available "Inline" and "Subscription".
Inline notifications options are used when Integrator is not registered and subscribed for notifications.
Subscription notification options are used when Integrator is registered and subscribed for notifications.
Check notifications are available for STS Cloud and STS Local (on-premises).
-
serviceCharges:
array serviceCharges
Array of service charges.
-
taxes:
array taxes
Array of tax item.
-
tenders:
array tenders
Array of tender items.
-
totals:
object CheckTotals
Contains a set of totals for aspects of the check. The values from the check total object relate in the following way:
subtotal (sum of menu items sales - discounts)
- discountTotal
+ autoServiceChargeTotal
+ serviceChargeTotal
+ taxTotal
- paymentTotal
= totalDue
array
-
Array of:
object CheckNotification
A notifiable event that occurred on this check. Read-only; incoming values will be ignored.
array
-
Array of:
object CheckComboMealItem
A Combo Meal that can be ordered.
array
-
Array of:
object CheckDiscountItem
Definition of a discount that can be applied to a transaction.
array
-
Array of:
object ExtensionItem
Object that can contain extensibility detail to be stored with the check.
object
-
checkEmployeeRef(required):
integer
The identifier of the employee that is used for the operations.Simphony: the employee object number.
-
checkName:
string
The reference for the check provided at time of check creation. This must be unique among all open checks at the revenue center. Note: The check name is being truncated on the POS client to 20 characters.
-
checkNumber:
integer
A check identifier generated by the POS when the check is created.
-
checkRef:
string
The unique check reference generated by the POS system when the check is created.
-
fireTime:
string(date-time)
The time requested for the order to "fire" to the kitchen. This is when preparation will start. If not provided, the current time is assumed. The dateTime in requests should be reflected in the Location/RVCs localized time, while responses will be shown in Zulu/UTC+0.
-
guestCount:
integer
The number of guests on the check.
-
idempotencyId(required):
string
Pattern:
[0-9a-f]{32}
A unique identifier for the request generated by the integrator. This should be a UUID v4 formatted value minus dashes. -
informationLines:
array informationLines
An array of strings containing text that may appear on the guest check. Consult the POS administrator to determine what is supported by their configuration.
-
isTrainingCheck:
boolean
Flag used to identify a training check.
-
language:
string
The language culture reference associated with the check. This value is used to return "name" property of check items in a desired language.
-
locRef(required):
string
The location identifier.
-
openTime:
string(date-time)
The time the check is opened/created. Time is UTC.
-
orderChannelRef:
integer
The order channel identifier from the revenue center configuration.
-
orderTypeRef(required):
integer
The order type identifier from the revenue center configuration.
-
orgShortName(required):
string
The organization identifier.
-
paymentStoreId:
string
An identifier of a payment store provided by the point of sale.
-
pickupTime:
string(date-time)
The time requested for the order to be collected. If not provided the current time plus the Service Level Time for the given order type is assumed. Time is local in the request but UTC in the response.
Service Level Time of the Order Channel takes priority (if non-zero) over the Service Level Time of the Order Type.
-
rvcRef(required):
integer
The revenue center identifier.
-
status:
string
Allowed Values:
[ "open", "closed" ]
Information about the status of the check. Status options:openindicates the check has a balance due and is 'open' (meaning it can be modified). closed indicates the check has been paid in full and is 'closed' (meaning it cannot be modified). -
tableGroupNumber:
integer
The table-group of the check. Assigned by POS and indicates the number of checks open checks with the same table.
-
tableName:
string
The table for the check from the revenue center configuration.tableName attribute can reflect either a single table number or a table name (in both cases represented by a string data type in the api). RVC option bit 18 is responsible for deciding if the value reflected in the tableName is utilized by the POS as the table name or the table number.
object
Integrator-provided options for notifications. Following NotificationOptions are available "Inline" and "Subscription".
Inline notifications options are used when Integrator is not registered and subscribed for notifications.
Subscription notification options are used when Integrator is registered and subscribed for notifications.
Check notifications are available for STS Cloud and STS Local (on-premises).
-
enabled(required):
boolean
A flag indicating whether notifications should be sent for the check. Set to true to request notifications. NotificationOptions "Inline" and "Subscription"
-
key:
string(string)
Integrator-provided HMAC SHA-256 key, with length 64 bytes. Base64 encoded string. Is required if 'enabled' is set to 'true' and per-check notifications are needed. NotificationOptions "Inline"
-
keyId:
string
Integrator-provided id for key. Is required if 'enabled' is set to 'true' and per-check notifications are needed. NotificationOptions "Inline"
-
url:
string
Integrator-provided web-hook callback URL. Must be able to accept POST requests. Is required if 'enabled' is set to 'true' and per-check notifications are needed. Must use port 443. NotificationOptions "Inline"Example:
https://your_web_hook_url:443/
array
-
Array of:
object CheckServiceChargeItem
A service charge that can be applied to a transaction.
array
-
Array of:
object CheckTaxItem
Array of tax item. If there were no taxable items on the check the returned array will be empty.
object
subtotal (sum of menu items sales - discounts)
- discountTotal
+ autoServiceChargeTotal
+ serviceChargeTotal
+ taxTotal
- paymentTotal
= totalDue
-
autoServiceChargeTotal:
number
The total of service charges automatically added to the check.
-
paymentTotal:
number
The total of the payments on the check.
-
serviceChargeTotal:
number
The service charge total of the check.
-
subtotal:
number
The subtotal of the check. This is the sum of net menu item totals. The net menu item total for a single menu item is (menu item total + item discounts + surcharge).
-
subtotalDiscountTotal:
number
The total of discounts applied to the subtotal.
-
taxTotal:
number
The tax total of the check. This value excludes any inclusive tax.
-
totalDue:
number
The remaining balance due for the check.
object
-
creationDate(required):
string
Message created date and time.
-
data(required):
object CheckNotificationMessagesData
The notification data.
-
id(required):
string
Message identifier.
-
messageType(required):
object CheckMessageType
Information about the type of message.
-
resource(required):
object CheckNotificationResource
Information about the STS resource affected by this message.
object
-
status:
string
Information about the preparation status of the check. Status options:
Expected for message Type: "CheckNotification". It is required to have the Kitchen Display System (KDS) configured to utilize the Check status notifications.Status Description Uninitialized indicates that the check was not fired. In use when pickupTime and fireTime is utilized in the request. Also returned when check status is "closed". Submitted indicates that the check preparation started. Prepared indicates that the check preparation was done. And moved "bumped" to the next stage. Packaged indicates that the check expedition was done. -
timeStampUtc:
string
A timestamp indicating the date and time in UTC at which check status changed.Expected for message Type: "CheckNotification"
{
"status":"Packaged",
"timeStampUtc":"2021-12-08T19:57:12.045Z"
}
object
-
id(required):
string
Identifier of the message type.Example:
{ "id":"CheckNotification" }
object
-
checkRef:
string
The unique check reference generated by the POS system when the check is created.
-
locRef:
string
The location identifier. (If present depending on the hierarchy level requested in subscription.)
-
orgShortName:
string
The organization identifier.
-
rvcRef:
string
The revenue center identifier.(If present depending on the hierarchy level requested in subscription.)
object
-
comboItem(required):
object CheckMenuItem
A menu item on the check represents an item that is purchased.
-
comboMealId(required):
integer
Combo meal object number.
-
extensions:
array extensions
Array of extension detail
-
mainItem(required):
object CheckMenuItem
A menu item on the check represents an item that is purchased.
-
seat:
integer
Seat assignment for the item.
-
sideItems(required):
array sideItems
Combo meal side items (for example, French Fries or Coke).
object
-
condiments:
array condiments
Array of condiments represented in menu item JSON objects. If there are no condiments configured, this array will be empty.
-
definitionSequence:
integer
The menu item definition sequence identifier. Indicates the definition of item that is used. This value is ignored on Oracle.RES platform.
-
extensions:
array extensions
Array of extension detail.
-
itemDiscounts:
array itemDiscounts
Array of discounts applied to the menu item.
- menuItemId(required): integer
-
name:
string
The name of the menu item defined in the POS.
-
priceSequence:
integer
The price sequence number to set the appropriate price level.
-
quantity:
number
The quantity of this menu item. If present minimum value is 1.
-
referenceText:
string
Maximum Length:
20
Additional text associated with the item. -
seat:
integer
Seat number of item on the check.
-
surcharge:
number
The calculated surcharge amount based on the rate configured for the surcharge associated with the item.
-
total:
number
The total cost of the item (extended to account for the quantity).
-
unitPrice:
number
The price associated with the item.
array
-
Array of:
object ExtensionItem
Object that can contain extensibility detail to be stored with the check.
array
-
Array of:
object CheckMenuItem
A menu item on the check represents an item that is purchased.
array
array
-
Array of:
object ExtensionItem
Object that can contain extensibility detail to be stored with the check.
array
-
Array of:
object CheckDiscountItem
Definition of a discount that can be applied to a transaction.
object
-
condimentId(required):
integer
The menu item's POS identifier.
-
definitionSequence(required):
integer
The menu item definition sequence identifier. Indicates the definition of item that is used. This value is ignored on Oracle.RES platform.
-
itemDiscounts:
array itemDiscounts
Array of discounts applied to the menu item.
-
name:
string
The name of the menu item defined in the POS.
-
priceSequence:
integer
The price sequence number to set the appropriate price level.
-
quantity:
number
The quantity of this item. If present minimum value is 1.
-
referenceText:
string
Additional text associated with the item.
-
seat:
integer
Seat number of item on the check.
-
surcharge:
number
Surcharge amount.
-
total:
number
Amount of item for the specified quantity.
-
unitPrice:
number
The price that should be used for the item.
array
-
Array of:
object CheckDiscountItem
Definition of a discount that can be applied to a transaction.
object
-
discountId(required):
integer
The discount identifier.
-
extensions:
array extensions
Array of extension detail.
-
isAutomatic:
boolean
Flag to indicate the item was applied by automatically by the POS system.
-
name:
string
The name of the discount defined in the POS.
-
referenceText:
string
Additional text associated with the discount.
-
seat:
integer
Seat number of item on the check.
-
total:
number
The value of the discount for the associated line number. In the request, if the discount is an open discount then set value to the amount (1.25) or percentage (0.1250 for 12.5%) that should be applied. For preset discounts the total property in the request is ignored. In the response, the total is the amount by which the transaction is discounted.
array
-
Array of:
object ExtensionItem
Object that can contain extensibility detail to be stored with the check.
object
-
appName:
string
The name of the application associated with this data (defined by the caller).
-
data:
string
The data payload for the extensibility data.
-
dataName:
string
Name of the data stored by this extensibility item.
-
dataType:
string
Describes the type of data stored by this extensibility item (defined by the caller).
-
displayName:
string
A string displayed and/or printed if this item is displayed or printed.
-
options:
array options
Array of options that define behavior of the extension item.
Option Description printOnDisplay When specified the displayName is shown on the display. printOnReceipt When specified the displayName is printed on the receipt/check. printInKitchen When specified the displayName is printed on the kitchen chit. Note: The printInKitchen option requires a custom extensibility application.
includeInApiResponse When specified the extension item is return as part of the check in the API responses.
array
Option | Description |
---|---|
printOnDisplay | When specified the displayName is shown on the display. |
printOnReceipt | When specified the displayName is printed on the receipt/check. |
printInKitchen | When specified the displayName is printed on the kitchen chit. Note: The printInKitchen option requires a custom extensibility application. |
includeInApiResponse | When specified the extension item is return as part of the check in the API responses. |
-
Array of:
string
Array of options. One or more of the following values are allowed: "printOnDisplay", "printOnReceipt", "printInKitchen", "includeInApiResponse"
[
"printondisplay",
"printonreceipt",
"printInKitchen",
"IncludeInApiResponse"
]
array
object
-
extensions:
array extensions
Array of extension detail.
-
name:
string
The name of the service charge.
-
referenceText:
string
Additional text associated with the service charge.
-
seat:
integer
Seat number of item on the check.
-
serviceChargeId(required):
integer
The service charge's object number reference.
-
total:
number
The value of the service charge. In the request, if the service charge is an _open_ then set value to the amount (1.25) or percentage (0.1250 for 12.5%) that should be applied. For preset a service charge the total property in the request is ignored. In the response, the total is the amount of the service charge applied to the check.
array
-
Array of:
object ExtensionItem
Object that can contain extensibility detail to be stored with the check.
object
-
name:
string
The name of the tax.
-
taxRateId(required):
string
The tax rate identifier.
-
total:
number
The total of the tax at for this rate.
object
-
chargedTipTotal:
number
The amount of charged tip to apply to the transaction. This amount is the portion of the payment that represents the charged tip. The chargedTipTotal field will not have an impact on a check if the "total" field is not specified.
-
extensions:
array extensions
Array of extension detail.
-
name:
string
The name of the tender defined in the POS.
-
paymentData:
object CheckPaymentData
Oracle Payment Interface data.
-
referenceText:
string
Additional text associated with the tender.
-
tenderId(required):
integer
Tender identifier.r
-
total:
number
The total of the tender item. A value of zero will result payment for the full amount.
array
-
Array of:
object ExtensionItem
Object that can contain extensibility detail to be stored with the check.
object
-
data(required):
object data
Object containing data for the type of payment.
-
type(required):
string
Describes the type of data contained in this payment data object.Type structure identifier, format identifier values can be found at link provided in the description.
object
400 Response
object
-
details:
string
A human-readable explanation specific to this occurrence of the problem.Example:
The Check provided is not valid.
-
instance:
string
A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.Example:
error:check_validation_failure
-
posDetails:
array posDetails
(Problem Details Extension) Contains a list of the problem details from the POS System processing the request.
-
title:
string
A short, human-readable summary of the problem type.Example:
Check is invalid.
-
type:
string
A URI reference that identifies the problem type. When this member is not present, its value is assumed to be "about:blank".Example:
error:validation
{
"type":"error:validation",
"title":"Check is invalid.",
"details":"The Check provided is not valid.",
"instance":"error:check_validation_failure",
"posDetails":[
{
"code":"menu_item_invalid",
"message":"invalid 'definitionSequence' value for menuItem '123'"
}
]
}
array
object
-
code:
string
Short, unique identifier for the type of errorExample:
menu_item_invalid
-
message:
string
A human-readable explanation specific to this occurrence of the problem.Example:
invalid 'definitionSequence' value for menuItem '123'
404 Response
521 Response
Examples
Example Request Body
Not applicable for this endpoint.
Example Response Body
The following example shows the contents of the response body in JSON format:
{
"items": [
{
"orgShortName": "string",
"locRef": "string",
"rvcRef": 0,
"checkRef": "string",
"idempotencyId": "f0f75b7d416deafaf1757b471b06c0c1",
"checkNumber": 0,
"checkName": "string",
"checkEmployeeRef": 0,
"orderTypeRef": 0,
"orderChannelRef": 0,
"tableName": "string",
"tableGroupNumber": 0,
"openTime": "2023-06-01T18:02:09.376Z",
"fireTime": "2023-06-01T18:02:09.376Z",
"pickupTime": "2023-06-01T18:02:09.376Z",
"guestCount": 0,
"language": "string",
"isTrainingCheck": true,
"informationLines": [
"string"
],
"paymentStoreId": "string",
"status": "open"
}
]
}