MCP tool reference

Use MCP tools/list for the schemas available to the current connection. Tools are exposed according to the customer's granted permissions. The release described here includes the tools below; environment availability can differ.

All IDs are positive safe integers. Amounts are nonnegative safe integers in the currency's minor units. JSON examples show MCP tools/call messages after the connection has been initialized. Use real identifiers from preceding tool responses.

Addresses

get_saved_addresses

Scope: addresses:read. Arguments: {}.

Returns the customer's saved addresses, including id, pretty_name, street details, city, state, country, and whether the address is currently active. Let the customer choose an address when the destination is unclear.

search_addresses

Scope: addresses:write.

Returns address suggestions with place_id and description. Searching does not save an address.

resolve_address

Scope: addresses:write.

Supply either place_id (1–300 characters) or both latitude and longitude. Do not combine a place ID with coordinates. Latitude must be between −90 and 90; longitude must be between −180 and 180. session_token is optional and follows the search token format.

Returns address fields and coordinates for review. Resolving does not save an address.

save_address

Scope: addresses:write. Effect: Saves a customer address.

Required fields are street, pretty_name, city, state, country, latitude, longitude, and confirmed: true. Address text fields must contain 1–255 characters after trimming. Optional fields are house_number, floor, direction (the same text limit), and tag (1–100 characters).

Ask the customer to confirm the resolved address and any missing details before saving. Use the returned id for restaurant search and checkout.

Restaurants and menus

search_restaurants

Scope: catalog:read.

Requires query (1–200 characters) and address_id. The address must belong to the customer. Results use that delivery address.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_restaurants",
    "arguments": { "query": "rice", "address_id": 101 }
  }
}

get_restaurant_menu

Scope: catalog:read.

Requires vendor_id. Optional menu_category_id filters a menu category. Use the returned item and modifier identifiers when building a cart.

Carts

create_cart

Scope: cart:write. Effect: Creates a delivery cart.

Requires vendor_id, address_id, and items (1–100 entries). Optional customer_vendor_note and customer_delivery_note accept up to 500 characters each.

Each item requires item_id, type: "menu", and quantity (1–50). Optional pack_reference accepts 1–100 characters. Optional modifiers accepts up to 30 objects, each containing id, menu_group_id, and quantity (1–50). Menu items and modifier objects accept only the fields described here; prices and container charges are derived by Chowdeck.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "create_cart",
    "arguments": {
      "vendor_id": 201,
      "address_id": 101,
      "items": [{ "item_id": 301, "type": "menu", "quantity": 1 }]
    }
  }
}

update_cart

Scope: cart:write. Effect: Updates the customer's cart for the vendor.

Uses the same argument structure as create_cart, with item quantities of 0–50. A zero quantity removes the corresponding item. Retrieve the resulting cart to verify the customer's intended contents before checkout.

get_cart

Scope: cart:write.

Requires vendor_id. Returns the customer's active cart for that vendor, including cart identifiers, items, totals, and notes.

Vouchers

discover_vouchers

Scope: catalog:read.

Optional arguments: currency (defaults to NGN), vendor_id, page (1–10,000; defaults to 1), and per_page (1–50; defaults to 20). Supported currency values are GHS, NGN, XAF, and XOF.

Returns eligible, discoverable vouchers the customer has not claimed. Each entry includes id, code, display_name, value_per_redemption, currency, expiry_time, vendor_ids, all_chowstore, redemptions_remaining, and security_question. Pagination is returned as meta.page, meta.per_page, and meta.has_more.

Discovery does not claim or reserve a voucher. Use vendor_id to filter offers for the selected restaurant; checkout performs the final eligibility check.

get_voucher_balances

Scope: checkout:write.

Accepts the same currency and pagination arguments as discovery, without vendor_id. Returns active positive balances, including vouchers claimed through other channels. Entries include user_promo_code_id, code, display_name, balance, currency, expiry_time, and vendor restrictions.

claim_voucher

Scope: checkout:write. Effect: Claims a voucher and consumes a redemption slot.

Requires code (1–100 characters). Optional currency defaults to NGN; optional security_answer accepts 1–255 characters. If an offer requires a security answer, obtain it from the customer. Never guess an answer.

Returns the claimed voucher's code, balance, currency, expiry, display name, and customer claim ID. Claim and failed-attempt limits apply. After an uncertain response, check existing balances before attempting another claim.

Checkout and payment

get_payment_options

Scope: checkout:write.

Requires currency (GHS, NGN, XAF, or XOF) and amount. Returns eligible wallet and saved card options with masked display labels. Use a returned card id as payment_method_id; request eligible options again if the payable amount changes.

prepare_checkout

Scope: checkout:write. Effect: Prepares a checkout quote and a short-lived confirmation token.

Returns data.checkout_id, data.expires_at, data.quote, and data.payment. The quote contains fingerprint, currency, and amounts. Preparation does not place or pay for the order.

confirm_checkout

Scope: checkout:write. Effect: Can create and pay for a real order.

Requires the checkout_id returned by preparation, the exact 64-character hexadecimal quote.fingerprint, and confirmed: true. Obtain explicit customer approval of the prepared checkout before calling this tool.

Confirmation expires after five minutes and is bound to the customer, client, and quote. A changed quote requires fresh preparation and approval. A consumed confirmation is rejected on repeat; the API does not promise to return the original success response on replay. Preserve any returned order ID for payment and order-status checks.

get_checkout_status

Scope: checkout:write.

Requires order_id. Returns order and payment status, including payment_status and time_payment_confirmed. It may requery an outstanding payment with the payment provider. Order creation alone does not mean payment succeeded.

Order tracking

get_order_status

Scope: orders:read.

Requires order_id. Returns the customer's order reference, status, summary, currency, total, relevant timestamps, and delivery PIN when available. Share the delivery PIN only with the customer in the appropriate order context.

get_order_timeline

Scope: orders:read.

Requires order_id. Returns the order timeline. The connected customer must own the order; shared-cart participation alone does not grant timeline access through MCP.

Reading results

Business results are returned in MCP structuredContent and as JSON text in content. Successful business results use status: "success". Failures use status: "failed" and set MCP isError: true; unexpected errors can return only an error text block. Protocol validation failures can also occur before a business result is produced.

Read isError and the returned payload. HTTP success is not sufficient evidence that a tool action succeeded. Messages may be translated; do not branch on exact English wording. See Troubleshooting.