Appearance
Ordering
Service path: /json/ordering
Ordering is a multi-step flow: validate the cart, validate items/options, then submit. The server owns pricing, availability, and time-slot capacity; the client builds an order object and re-validates it until it is accepted.
The order object
Every ordering method takes (or returns) an order. The fields the app sets:
json
{
"userId": "{USER_ID}",
"institutionId": "{INSTITUTION_UUID}",
"merchantId": "{MERCHANT_ID}",
"menuId": "{MENU_ID}",
"type": 0,
"dueTime": "2026-11-19T12:00:00",
"isAutoAsapSelection": false,
"mealBased": false,
"deliveryAddressId": null,
"pickupAddressId": "{ADDRESS_ID}",
"userPhone": "555-555-5555",
"notes": "",
"tip": 0,
"tax": 0,
"subTotal": 12.5,
"deliveryFee": 0,
"pickupFee": 0,
"useFee": 0,
"discount": 0,
"total": 12.5,
"orderItems": [ ],
"orderPayment": [ ]
}| Field | Meaning |
|---|---|
type | 0 pickup, 1 delivery, 2 dine-in |
dueTime | Requested time. Omitted for ASAP orders |
isAutoAsapSelection | Whether ASAP was auto-selected |
mealBased | Menu is meal-plan based |
deliveryAddressId / pickupAddressId | One of these, depending on type |
userPhone | Contact phone (required by some merchants) |
tip, tax, subTotal, total | Computed client-side, then re-validated |
orderItems | Array of item objects |
orderPayment | Array with one { accountId } object, or null for rollup |
An order item:
json
{
"menuItemId": "{MENU_ITEM_ID}",
"quantity": 1,
"salePrice": 8.5,
"notes": "",
"orderItemOptions": [
{ "optionId": "{OPTION_ID}", "quantity": 1, "salePrice": 1.0 }
]
}Rollup accounts
A rollup account is not a real account id. Before any ordering call the app rewrites:
orderPayment = []whenorderPayment[0].accountId === "rollup".accountId/accountID→nullwhen the value is"rollup".
If you send the literal string rollup the server rejects the order.
Validate an Order
Prices the cart, checks availability, and returns the order with computed totals and the next valid due time.
plaintext
POST /json/ordering
method: validateOrderjson
{
"method": "validateOrder",
"params": {
"order": { "...": "order object" },
"sessionId": "{SESSION_ID}"
}
}Success Response
json
{
"response": {
"dueTime": "2026-11-19T12:15:00",
"subTotal": 12.5,
"tax": 0.63,
"total": 13.13,
"orderItems": [ ],
"orderRemovedItems": [ ],
"orderPayment": [ ]
},
"exception": null
}Validation errors
The response (or the exception string) may contain ordering codes. The app maps them to messages:
| Code | Enum | Message |
|---|---|---|
9001 | DELIVERY_ADDRESS_COORDS | The selected delivery address could not be mapped to valid coordinates. |
9002 | ORDER_DELIVERY_ITEM_MIN | Order minimum total for delivery wasn't met |
9003 | ORDER_TYPE | Merchant does not support the requested order type |
9004 | CONTACT_INFO | There was an issue with the transaction, user phone number missing and required |
9005 | ORDER_ITEM_MIN | Items in order couldn't be lower than merchant supports |
9006 | ORDER_ITEM_MAX | Items in order couldn't be more than merchant supports |
9007 | ITEM_OPTION_MIN | Missing a required option selection |
9008 | ITEM_OPTION_MAX | Exceeded the maximum option selections |
9009 | ORDER_PAYMENT | Unexpected problem submitting payment |
9010 | INVALID_ORDER | Incorrect time for menu item |
9011 | MERCHANT_CLOSED | The merchant is currently closed |
9012 | MENU_UNAVAILABLE | Menu is not available at this time |
9013 | ORDER_STATUS | Order cannot be canceled because it is completed |
9014 | ORDER_TIP | Tip is negative or greater than the subtotal |
9016 | DUPLICATE_ORDER | Duplicate order submission |
9017 | ORDER_CAPACITY | Due time exceeds merchant order capacity |
9023 | NOT_AVAILABLE_SLOTS | All time slots exhausted |
9024 | INVALID_ITEMS_FOR_DUE_TIME | Order has invalid items for the due time |
6112 | INSUFFICIENT_FUNDS | You don't have enough money |
6113 | PAYMENT_SYSTEM_EXCEPTION | Payment processor error |
6001 | INVALID_CARD | Invalid card |
6102 | MEDIA_LOST | The specified card has been reported lost |
9801 | — | The attempted order contains invalid items for the menu |
9997 | TIMEOUT | Timeout error, please try again later |
Validate Order Items
Re-checks only the items (availability, options, prices) without pricing payment.
plaintext
POST /json/ordering
method: validateOrderItems| Field | Type | Required | Description |
|---|---|---|---|
order | object | YES | Order object. |
validateOrderResult | boolean | object | NO | Defaults to true in the app. |
json
{
"method": "validateOrderItems",
"params": {
"order": { "...": "order object" },
"validateOrderResult": true,
"sessionId": "{SESSION_ID}"
}
}Response includes orderRemovedItems, an array of items that are no longer available.
Validate Items to Add to an Existing Order
Used when adding items to a pending order.
plaintext
POST /json/ordering
method: validateOrderAddOnsThe params are the order fields spread at the top level, plus:
| Field | Type | Required | Description |
|---|---|---|---|
orderID | string | YES | Existing pending order id. |
itemsToAdd | array | YES | Items to add. |
accountID | string | null | YES | Payment account; null for rollup. |
json
{
"method": "validateOrderAddOns",
"params": {
"orderID": "{ORDER_ID}",
"itemsToAdd": [ { "menuItemId": "{MENU_ITEM_ID}", "quantity": 1 } ],
"accountID": "{ACCOUNT_ID}",
"sessionId": "{SESSION_ID}"
}
}IMPORTANT
Note accountID (capital ID) here, while submitOrder uses accountId.
Add Items to a Pending Order
plaintext
POST /json/ordering
method: addItemsToOrderSame parameter shape as validateOrderAddOns, plus cvv when a card payment is needed:
json
{
"method": "addItemsToOrder",
"params": {
"clientAddItemsID": "{CLIENT_UUID}",
"orderID": "{ORDER_ID}",
"itemsToAdd": [ { "menuItemId": "{MENU_ITEM_ID}", "quantity": 1 } ],
"cvv": "123",
"accountID": "{ACCOUNT_ID}",
"sessionId": "{SESSION_ID}"
}
}Submit an Order
plaintext
POST /json/ordering
method: submitOrder| Field | Type | Required | Description |
|---|---|---|---|
order | object | YES | Validated order. Must include clientOrderID. |
accountId | string | null | YES | Payment account; null for rollup. |
cvv | string | null | NO | Card CVV. |
sessionId | string | YES | Injected. |
json
{
"method": "submitOrder",
"params": {
"order": { "...": "order object with clientOrderID" },
"accountId": "{ACCOUNT_ID}",
"cvv": "123",
"sessionId": "{SESSION_ID}"
}
}TIP
clientOrderID is a client-generated UUID. It makes submission idempotent — resending the same id returns the existing order instead of creating a duplicate. If the app times out it re-submits the same id.
Success Response
json
{
"response": {
"id": "{ORDER_ID}",
"orderNumber": "1234",
"status": 1,
"dueTime": "2026-11-19T12:15:00",
"total": 13.13
},
"exception": null
}Cancel an Order
plaintext
POST /json/ordering
method: cancelOrderjson
{
"method": "cancelOrder",
"params": { "orderId": "{ORDER_ID}", "sessionId": "{SESSION_ID}" }
}Check In to an Order
Marks a ready/pending order as picked up (or arrived) when the patron is at the merchant. Two modes share one method.
plaintext
POST /json/ordering
method: checkInOrder| Field | Type | Required | Description |
|---|---|---|---|
orderId | string | YES | The order to check in. |
latitude | number | null | NO | Device latitude for location check-in, otherwise null. |
longitude | number | null | NO | Device longitude for location check-in, otherwise null. |
checkinBarcode | string | null | NO | Scanned barcode value, otherwise null. |
sessionId | string | YES | Injected. |
The app offers both modes in a dialog:
| Mode | Params sent |
|---|---|
| Location check-in | Real latitude/longitude from the device; checkinBarcode: null. |
| Scan code | latitude: null, longitude: null; the scanned checkinBarcode. |
json
{
"method": "checkInOrder",
"params": {
"orderId": "{ORDER_ID}",
"latitude": 43.073052,
"longitude": -89.40123,
"checkinBarcode": null,
"sessionId": "{SESSION_ID}"
}
}A truthy response means the check-in succeeded (the app then shows the success screen and navigates to the order detail). A failed check-in throws an error whose message is shown in the failure dialog.
NOTE
Location check-in asks for location permission first. If it is denied the app shows patron-ui.checkin.no_permissions and does not call the method.
Order History
Recent successful orders
plaintext
POST /json/ordering
method: retrieveSuccessfulOrdersList| Field | Type | Required | Description |
|---|---|---|---|
userId | string | YES | User id. |
merchantId | null | NO | Always null in the app. |
maxReturn | number | NO | Page size; the app uses 30. |
json
{
"method": "retrieveSuccessfulOrdersList",
"params": {
"userId": "{USER_ID}",
"merchantId": null,
"maxReturn": 30,
"sessionId": "{SESSION_ID}",
"institutionId": "{INSTITUTION_UUID}"
}
}Response is { "list": [ ... ] }.
Query orders
plaintext
POST /json/ordering
method: retrieveOrderListThis is the filtered variant used by the order-history screen. maxReturn is forced to 0 (unlimited); the filters do the work.
| Field | Type | Description |
|---|---|---|
userId | string | User id. |
merchantId | string | Always "" (all merchants) in the app. |
institutionId | string | Always "" in the app; the real value is injected. |
startDate | string | ISO start of the selected period. |
endDate | string | ISO end of the selected period. |
orderStatuses | number[] | Status groups, see below. |
maxReturn | number | Always 0 (unlimited). |
sessionId / institutionId | string | Injected. |
Period options are past_six_month (default, last 180 days), past_month (last 30 days), or a specific month sent as {startDate, endDate} computed from that month.
The UI's status tabs map to status arrays:
| Tab | orderStatuses |
|---|---|
| All | 2,3,4,6,7,11,5,8,9,10,1 (every status) |
| Pending | 1 |
| Completed | 2,3,4,6,7,11,5 |
| Canceled | 8,9,10 |
Response is { "list": [ ... ] }, same order objects as the recent list, keyed by orderStatus (see order status). The app also derives a display merchantName by matching merchantId against the menu merchants.
Merchant Order Schedule
Returns the merchant's available order windows for a given order type.
plaintext
POST /json/ordering
method: getMerchantOrderSchedule| Field | Type | Required | Description |
|---|---|---|---|
merchantId | string | YES | Merchant id. |
orderType | number | YES | 0 pickup, 1 delivery, 2 dine-in. |
startDate | null | NO | Always null in the app. |
endDate | null | NO | Always null. |
json
{
"method": "getMerchantOrderSchedule",
"params": {
"merchantId": "{MERCHANT_ID}",
"orderType": 0,
"startDate": null,
"endDate": null,
"sessionId": "{SESSION_ID}"
}
}NOTE
getMerchantOrderSchedule is flagged useInstitutionId = false in the app, so only sessionId is injected.