Skip to content

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": [ ]
}
FieldMeaning
type0 pickup, 1 delivery, 2 dine-in
dueTimeRequested time. Omitted for ASAP orders
isAutoAsapSelectionWhether ASAP was auto-selected
mealBasedMenu is meal-plan based
deliveryAddressId / pickupAddressIdOne of these, depending on type
userPhoneContact phone (required by some merchants)
tip, tax, subTotal, totalComputed client-side, then re-validated
orderItemsArray of item objects
orderPaymentArray 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 = [] when orderPayment[0].accountId === "rollup".
  • accountId / accountID → null when 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: validateOrder
json
{
    "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:

CodeEnumMessage
9001DELIVERY_ADDRESS_COORDSThe selected delivery address could not be mapped to valid coordinates.
9002ORDER_DELIVERY_ITEM_MINOrder minimum total for delivery wasn't met
9003ORDER_TYPEMerchant does not support the requested order type
9004CONTACT_INFOThere was an issue with the transaction, user phone number missing and required
9005ORDER_ITEM_MINItems in order couldn't be lower than merchant supports
9006ORDER_ITEM_MAXItems in order couldn't be more than merchant supports
9007ITEM_OPTION_MINMissing a required option selection
9008ITEM_OPTION_MAXExceeded the maximum option selections
9009ORDER_PAYMENTUnexpected problem submitting payment
9010INVALID_ORDERIncorrect time for menu item
9011MERCHANT_CLOSEDThe merchant is currently closed
9012MENU_UNAVAILABLEMenu is not available at this time
9013ORDER_STATUSOrder cannot be canceled because it is completed
9014ORDER_TIPTip is negative or greater than the subtotal
9016DUPLICATE_ORDERDuplicate order submission
9017ORDER_CAPACITYDue time exceeds merchant order capacity
9023NOT_AVAILABLE_SLOTSAll time slots exhausted
9024INVALID_ITEMS_FOR_DUE_TIMEOrder has invalid items for the due time
6112INSUFFICIENT_FUNDSYou don't have enough money
6113PAYMENT_SYSTEM_EXCEPTIONPayment processor error
6001INVALID_CARDInvalid card
6102MEDIA_LOSTThe specified card has been reported lost
9801—The attempted order contains invalid items for the menu
9997TIMEOUTTimeout 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
FieldTypeRequiredDescription
orderobjectYESOrder object.
validateOrderResultboolean | objectNODefaults 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: validateOrderAddOns

The params are the order fields spread at the top level, plus:

FieldTypeRequiredDescription
orderIDstringYESExisting pending order id.
itemsToAddarrayYESItems to add.
accountIDstring | nullYESPayment 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: addItemsToOrder

Same 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
FieldTypeRequiredDescription
orderobjectYESValidated order. Must include clientOrderID.
accountIdstring | nullYESPayment account; null for rollup.
cvvstring | nullNOCard CVV.
sessionIdstringYESInjected.
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: cancelOrder
json
{
    "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
FieldTypeRequiredDescription
orderIdstringYESThe order to check in.
latitudenumber | nullNODevice latitude for location check-in, otherwise null.
longitudenumber | nullNODevice longitude for location check-in, otherwise null.
checkinBarcodestring | nullNOScanned barcode value, otherwise null.
sessionIdstringYESInjected.

The app offers both modes in a dialog:

ModeParams sent
Location check-inReal latitude/longitude from the device; checkinBarcode: null.
Scan codelatitude: 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
FieldTypeRequiredDescription
userIdstringYESUser id.
merchantIdnullNOAlways null in the app.
maxReturnnumberNOPage 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: retrieveOrderList

This is the filtered variant used by the order-history screen. maxReturn is forced to 0 (unlimited); the filters do the work.

FieldTypeDescription
userIdstringUser id.
merchantIdstringAlways "" (all merchants) in the app.
institutionIdstringAlways "" in the app; the real value is injected.
startDatestringISO start of the selected period.
endDatestringISO end of the selected period.
orderStatusesnumber[]Status groups, see below.
maxReturnnumberAlways 0 (unlimited).
sessionId / institutionIdstringInjected.

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:

TaborderStatuses
All2,3,4,6,7,11,5,8,9,10,1 (every status)
Pending1
Completed2,3,4,6,7,11,5
Canceled8,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
FieldTypeRequiredDescription
merchantIdstringYESMerchant id.
orderTypenumberYES0 pickup, 1 delivery, 2 dine-in.
startDatenullNOAlways null in the app.
endDatenullNOAlways 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.