Skip to content

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 }
    ]
}
KeyValueMeaning
open_nowboolOnly merchants open right now
activeboolOnly active merchants
tagsstring / arrayFilter by tag
addedAfterDatedateOnly merchants added after a date
addressstringFree-text address search
latitudenumberUser latitude
longitudenumberUser longitude
order_typenumber0 pickup, 1 delivery, 2 dine-in
menu_searchstringSearch menu items
include_order_typesboolInclude order-type metadata
limit_by_delivery_distanceboolOnly merchants delivering to the user
merchant_idstringRestrict to one merchant
include_settings1Include 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: getMerchants
json
{
    "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
}
FieldMeaning
openNowAccepting orders right now
distanceFromUserDistance from the supplied lat/long
walkoutSmart Shopping merchant — browse only, cannot order
orderTypes.pickup / .deliveryWhich order types the merchant supports
pickupPrepTime / deliveryPrepTimePrep time in minutes (used for ASAP estimates)
hasMealBasedMenu / hasCurrencyBasedMenuWhich tenders have a menu
imageThumbnail / imageFullPath fragments — prepend the image base (below)
storeAddress, hoursOfOperation, paymentNotes, descriptionExplore detail fields
emailCustomerService, phoneCustomerService, faxNumber, websiteContact fields
timeZoneMerchant 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 — true only when the merchant is in the getMenuMerchants response and the institution has get.feature.enable_food enabled.

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: getMenuMerchants

Same 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
FieldTypeRequiredDescription
excludeNonOrderingbooleanYESAlways false in the app.
json
{
    "method": "getFavoriteMerchants",
    "params": { "excludeNonOrdering": false, "sessionId": "{SESSION_ID}" }
}

Response is { "list": [ ... ] }.

Add ​

plaintext
POST /json/merchant
method: addFavoriteMerchant
json
{
    "method": "addFavoriteMerchant",
    "params": {
        "merchantId": "{MERCHANT_ID}",
        "notes": "",
        "sessionId": "{SESSION_ID}"
    }
}

Remove ​

plaintext
POST /json/merchant
method: removeFavoriteMerchant
json
{
    "method": "removeFavoriteMerchant",
    "params": { "merchantId": "{MERCHANT_ID}", "sessionId": "{SESSION_ID}" }
}

Get Merchant Settings ​

plaintext
POST /json/merchant
method: getMerchantSettings
FieldTypeRequiredDescription
merchantIdstringYESMerchant id.
domainnullNOAlways null in the app.
categorynullNOAlways null.
namenullNOAlways null.
json
{
    "method": "getMerchantSettings",
    "params": {
        "merchantId": "{MERCHANT_ID}",
        "domain": null,
        "category": null,
        "name": null,
        "sessionId": "{SESSION_ID}"
    }
}

Merchant setting keys ​

KeyMeaning
merchant.order.delivery_address_restrictionDelivery restricted to campus
merchant.order.pickup_locations_enabledPickup locations enabled
merchant.order.order_ahead_enabledScheduled orders
merchant.order.disable_item_notesDisable item notes
merchant.order.disable_order_notesDisable order notes
merchant.order.enableAutoASAPSelectionAuto-select ASAP
merchant.tip.enable_tipTips enabled
merchant.menu.menu_barcode_enabledScan-to-add
merchant.menu.menu_add_barcodea_enabledManual barcode entry
merchant.menu.menu_add_items_enabledAdd-to-cart
merchant.payment.supported_typesJSON array of { payment_system_type }
merchant.payment.removeTaxCheckoutHide tax at checkout

Single menu ​

plaintext
POST /json/merchant
method: getDisplayMenu
FieldTypeRequiredDescription
merchantIdstringYESMerchant id.
dateTimestringYESISO timestamp for the menu.
orderTypenumberYES0 pickup, 1 delivery, 2 dine-in.
localenullNOAlways null.
depthnumberNOMenu-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: getDisplayMenus

Identical 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.

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:

  1. menuCategoryItems[] entry: keep only when active && visible and the contained menuItem is active && visible && !deleted.
  2. menuGroupItems[] entry: same rule applied to its nested menuItem.
  3. A menu group with minimum > 0 is required; maximum caps how many options may be picked. When maximum === 1 the UI renders a radio list, otherwise a checkbox list.
  4. Option rows show menuItem.price as an up-charge (only when non-zero); prices are resolved through the meal-based formatter when menu.mealBased is 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
FieldTypeRequired
merchantIdstringYES
sessionIdstringInjected
institutionIdstringInjected

Response is an array of addresses; the app wraps each as { addressInfo: address }.

Delivery Area Check ​

plaintext
POST /json/merchant
method: isOutsideMerchantDeliveryArea
FieldTypeRequired
merchantIdstringYES
latitudenumberYES
longitudenumberYES

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
FieldTypeRequiredDescription
merchantIdstringYESMerchant id.
optionsobject | nullNO{ menuId, total } when filtering.
userIdstringYESUser id.
sessionIdstringYESInjected.
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.