Appearance
Merchants
Service path: /json/merchant
Merchant calls power Explore (places), favorites, menus, pickup/delivery checks, and payment-account filtering for orders.
Search Options
getMerchants and getMenuMerchants take an array of search options:
json
{
"searchOptions": [
{ "key": "include_settings", "value": 1 },
{ "key": "latitude", "value": 42.34 },
{ "key": "longitude", "value": -71.09 }
]
}| Key | Value | Meaning |
|---|---|---|
open_now | bool | Only merchants open right now |
active | bool | Only active merchants |
tags | string / array | Filter by tag |
addedAfterDate | date | Only merchants added after a date |
address | string | Free-text address search |
latitude | number | User latitude |
longitude | number | User longitude |
order_type | number | 0 pickup, 1 delivery, 2 dine-in |
menu_search | string | Search menu items |
include_order_types | bool | Include order-type metadata |
limit_by_delivery_distance | bool | Only merchants delivering to the user |
merchant_id | string | Restrict to one merchant |
include_settings | 1 | Include the merchant settings map |
IMPORTANT
The app always adds include_settings = 1. Without it the response has no settings.map, and ordering features (tips, notes, barcodes, supported payment types) appear disabled.
List Merchants
plaintext
POST /json/merchant
method: getMerchantsjson
{
"method": "getMerchants",
"params": {
"searchOptions": [
{ "key": "include_settings", "value": 1 },
{ "key": "latitude", "value": 42.34 },
{ "key": "longitude", "value": -71.09 }
],
"sessionId": "{SESSION_ID}",
"institutionId": "{INSTITUTION_UUID}"
}
}Response:
json
{
"response": {
"list": [
{
"id": "{MERCHANT_ID}",
"name": "Dining Hall",
"openNow": true,
"distanceFromUser": 0.3,
"walkout": false,
"orderTypes": {
"pickup": true,
"delivery": true,
"pickupPrepTime": 10,
"deliveryPrepTime": 25
},
"hasMealBasedMenu": true,
"hasCurrencyBasedMenu": true,
"imageThumbnail": "{IMAGE_PATH_FRAGMENT}",
"imageFull": "{IMAGE_PATH_FRAGMENT}",
"storeAddress": "1 Main St",
"hoursOfOperation": "Mon-Fri 7am-9pm",
"timeZone": "America/New_York",
"settings": {
"map": {
"merchant.tip.enable_tip": { "value": "1" },
"merchant.payment.supported_types": {
"value": "[{\"payment_system_type\":4}]"
}
}
}
}
]
},
"exception": null
}| Field | Meaning |
|---|---|
openNow | Accepting orders right now |
distanceFromUser | Distance from the supplied lat/long |
walkout | Smart Shopping merchant — browse only, cannot order |
orderTypes.pickup / .delivery | Which order types the merchant supports |
pickupPrepTime / deliveryPrepTime | Prep time in minutes (used for ASAP estimates) |
hasMealBasedMenu / hasCurrencyBasedMenu | Which tenders have a menu |
imageThumbnail / imageFull | Path fragments — prepend the image base (below) |
storeAddress, hoursOfOperation, paymentNotes, description | Explore detail fields |
emailCustomerService, phoneCustomerService, faxNumber, website | Contact fields |
timeZone | Merchant time zone for due-time formatting |
Images are not full URLs. The app builds them as {imageBaseUrl}{imageThumbnail} where the base is https://object-store.api.cbord.com/image/ in production (see Environments).
Two fields are added client-side and are not returned by the API:
isFavorite— from the favorites list union.isAbleToOrder—trueonly when the merchant is in thegetMenuMerchantsresponse and the institution hasget.feature.enable_foodenabled.
NOTE
settings.map values are strings. merchant.payment.supported_types is a JSON-encoded array. The app parses it with JSON.parse and falls back to [].
List Merchants With Menus
plaintext
POST /json/merchant
method: getMenuMerchantsSame parameters and response as getMerchants; returns only merchants that have an orderable menu for the current context. Used by the ordering flow.
Favorites
List
plaintext
POST /json/merchant
method: getFavoriteMerchants| Field | Type | Required | Description |
|---|---|---|---|
excludeNonOrdering | boolean | YES | Always false in the app. |
json
{
"method": "getFavoriteMerchants",
"params": { "excludeNonOrdering": false, "sessionId": "{SESSION_ID}" }
}Response is { "list": [ ... ] }.
Add
plaintext
POST /json/merchant
method: addFavoriteMerchantjson
{
"method": "addFavoriteMerchant",
"params": {
"merchantId": "{MERCHANT_ID}",
"notes": "",
"sessionId": "{SESSION_ID}"
}
}Remove
plaintext
POST /json/merchant
method: removeFavoriteMerchantjson
{
"method": "removeFavoriteMerchant",
"params": { "merchantId": "{MERCHANT_ID}", "sessionId": "{SESSION_ID}" }
}Get Merchant Settings
plaintext
POST /json/merchant
method: getMerchantSettings| Field | Type | Required | Description |
|---|---|---|---|
merchantId | string | YES | Merchant id. |
domain | null | NO | Always null in the app. |
category | null | NO | Always null. |
name | null | NO | Always null. |
json
{
"method": "getMerchantSettings",
"params": {
"merchantId": "{MERCHANT_ID}",
"domain": null,
"category": null,
"name": null,
"sessionId": "{SESSION_ID}"
}
}Merchant setting keys
| Key | Meaning |
|---|---|
merchant.order.delivery_address_restriction | Delivery restricted to campus |
merchant.order.pickup_locations_enabled | Pickup locations enabled |
merchant.order.order_ahead_enabled | Scheduled orders |
merchant.order.disable_item_notes | Disable item notes |
merchant.order.disable_order_notes | Disable order notes |
merchant.order.enableAutoASAPSelection | Auto-select ASAP |
merchant.tip.enable_tip | Tips enabled |
merchant.menu.menu_barcode_enabled | Scan-to-add |
merchant.menu.menu_add_barcodea_enabled | Manual barcode entry |
merchant.menu.menu_add_items_enabled | Add-to-cart |
merchant.payment.supported_types | JSON array of { payment_system_type } |
merchant.payment.removeTaxCheckout | Hide tax at checkout |
Menus
Single menu
plaintext
POST /json/merchant
method: getDisplayMenu| Field | Type | Required | Description |
|---|---|---|---|
merchantId | string | YES | Merchant id. |
dateTime | string | YES | ISO timestamp for the menu. |
orderType | number | YES | 0 pickup, 1 delivery, 2 dine-in. |
locale | null | NO | Always null. |
depth | number | NO | Menu-tree depth; the app uses 4. |
json
{
"method": "getDisplayMenu",
"params": {
"merchantId": "{MERCHANT_ID}",
"dateTime": "2026-11-19T12:00:00.000Z",
"orderType": 0,
"locale": null,
"depth": 4,
"sessionId": "{SESSION_ID}"
}
}Multiple menus
plaintext
POST /json/merchant
method: getDisplayMenusIdentical parameters. Returns menus for all order types / periods at once.
TIP
depth: 4 returns categories → items → options → option values. Lower values return a shallower tree and are cheaper.
Menu tree shape
getDisplayMenu returns a menu object. The hierarchy the app walks is:
plaintext
menu
└─ menuCategories[]
├─ id, name
└─ menuCategoryItems[]
├─ active, visible
└─ menuItem
├─ id, name, description, price, imageReference
├─ active, visible, deleted
├─ nutritionInfo[] ({ name, displayValue }; calories is name "calories")
├─ allergens[] (strings)
└─ menuItemOptions[]
├─ menuGroup { name, minimum, maximum, menuGroupItems[] }
└─ (each menuGroupItem: active, visible, menuItem)The app filters out entries in this order at each level:
menuCategoryItems[]entry: keep only whenactive && visibleand the containedmenuItemisactive && visible && !deleted.menuGroupItems[]entry: same rule applied to its nestedmenuItem.- A menu group with
minimum > 0is required;maximumcaps how many options may be picked. Whenmaximum === 1the UI renders a radio list, otherwise a checkbox list. - Option rows show
menuItem.priceas an up-charge (only when non-zero); prices are resolved through the meal-based formatter whenmenu.mealBasedis true.
imageReference is a path fragment, not a full URL: build the URL with the environment's image base (https://object-store.api.cbord.com/image/ in production). See Environments.
NOTE
A merchant's openNow, walkout, and orderTypes (pickup, delivery) flags come back on the merchant objects from getMenuMerchants/getMerchants, not from the menu itself. walkout merchants (Smart Shopping) cannot be ordered through the API; the app blocks them with Ordering is not possible for Smart Shopping merchants....
Pickup Locations
plaintext
POST /json/merchant
method: retrievePickupAddressesInRange| Field | Type | Required |
|---|---|---|
merchantId | string | YES |
sessionId | string | Injected |
institutionId | string | Injected |
Response is an array of addresses; the app wraps each as { addressInfo: address }.
Delivery Area Check
plaintext
POST /json/merchant
method: isOutsideMerchantDeliveryArea| Field | Type | Required |
|---|---|---|
merchantId | string | YES |
latitude | number | YES |
longitude | number | YES |
Response is a boolean (true = outside the delivery area).
Payment Accounts for a Merchant
Returns which accounts can pay at a merchant, optionally filtered by a specific menu and order total.
plaintext
POST /json/merchant
method: getMerchantPaymentAccountsWithFilter| Field | Type | Required | Description |
|---|---|---|---|
merchantId | string | YES | Merchant id. |
options | object | null | NO | { menuId, total } when filtering. |
userId | string | YES | User id. |
sessionId | string | YES | Injected. |
json
{
"method": "getMerchantPaymentAccountsWithFilter",
"params": {
"merchantId": "{MERCHANT_ID}",
"options": { "menuId": "{MENU_ID}", "total": 12.5 },
"userId": "{USER_ID}",
"sessionId": "{SESSION_ID}"
}
}Response is { accounts: [ ... ] }.
NOTE
Guests only ever see USAePay accounts here; the app filters the list client-side.