Ordering and vouchers

This guide follows a customer from restaurant discovery to a paid order. The JSON blocks are MCP tools/call requests after client initialization. All IDs, codes, and tokens are illustrative; use values returned for the connected customer.

Test in sandbox first

Complete Sandbox setup before running this flow in development. Get your test key from Settings → Developers in the Chowdeck dashboard, use it to access the sandbox console, and connect your MCP client to https://console-api.chowdeck.com/mcp using customer OAuth. The dashboard test key is for console access; it does not replace the customer OAuth bearer token.

Use sandbox identifiers returned by sandbox tools throughout the flow.

Choose the delivery address and restaurant

Call get_saved_addresses, then use the customer's chosen address in search_restaurants. If a new address is needed, use search_addresses and resolve_address, review the result with the customer, and call save_address with confirmed: true.

Call get_restaurant_menu for the chosen vendor. Resolve required modifiers and quantities with the customer, then call create_cart. Inspect the returned cart and keep its cart ID for checkout. Later edits use update_cart and get_cart.

Check offers and existing balances

Use discover_vouchers to find new offers and get_voucher_balances to find vouchers the customer already holds. These lists serve different purposes: claiming an offer removes it from that customer's discovery results, while its usable balance appears in the balances list.

For a chosen restaurant:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "discover_vouchers",
    "arguments": { "currency": "NGN", "vendor_id": 201, "page": 1, "per_page": 20 }
  }
}

An offer can disappear if another customer takes its final redemption slot. Discovery does not reserve a slot. Phone restrictions, expiry, currency, available slots, and claim limits still apply.

Claim a selected offer

Claim only after the customer asks to claim the offer. If security_question is present, ask for the customer's answer and pass it as security_answer.

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "claim_voucher",
    "arguments": { "code": "EXAMPLECODE", "currency": "NGN" }
  }
}

A successful claim creates a customer voucher balance. It does not place an order or spend the balance. Existing voucher balances remain separate. A claimed balance can be used through supported Chowdeck channels, subject to its restrictions.

If the response is lost or the request times out, call get_voucher_balances to check whether the claim succeeded before retrying. Do not claim an existing balance again.

Prepare checkout

Use get_payment_options to select an eligible wallet or saved card. Then call prepare_checkout, including the selected voucher code in promo_codes when applicable:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "prepare_checkout",
    "arguments": {
      "cart_id": 401,
      "address_id": 101,
      "payment_method": "wallet",
      "promo_codes": ["EXAMPLECODE"],
      "tip": 0
    }
  }
}

The quote is authoritative for prices, delivery charges, discounts, voucher eligibility, and the payable amount. Use its returned amounts instead of subtracting the voucher balance yourself. An order can still require payment when a voucher covers only part of the cost.

Obtain approval and confirm

Present the cart contents, destination, payment option, voucher application, and quoted amounts. Ask the customer to approve the order before confirmation.

Pass the returned data.checkout_id and data.quote.fingerprint unchanged:

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "confirm_checkout",
    "arguments": {
      "checkout_id": "CHECKOUT_ID_FROM_PREPARE",
      "fingerprint": "FINGERPRINT_FROM_PREPARE",
      "confirmed": true
    }
  }
}

The strings above are placeholders, not valid confirmation credentials. Confirm within the returned expiry window, which is five minutes. If items, charges, or payment details change, prepare a fresh quote and obtain approval for that quote.

Verify payment and track delivery

Keep the order ID from a successful confirmation response. Call get_checkout_status to check whether payment completed. Do not describe a pending payment as paid.

Use get_order_status and get_order_timeline for subsequent progress. Refresh get_voucher_balances when the customer asks how much voucher credit remains.

If a confirmation response is lost, preserve the checkout attempt and any returned order information. Check a known order's checkout status. A repeated confirmation can return a consumed-confirmation error; do not automatically create a new checkout and risk a second order. If the outcome cannot be established, use the Chowdeck app or contact support to reconcile the attempt before placing another order.

Sandbox order simulation

After creating an order through sandbox MCP, use the console to test how your application handles its progress:

1. Preserve the order ID returned by confirm_checkout. Order creation alone does not prove payment succeeded; check get_checkout_status.
2. Open the sandbox console with the test key from your Chowdeck dashboard.
3. Find the order created through MCP and use the available simulation controls to advance its progress. Exercise cancellation or failure states where the console provides them.
4. Fetch get_order_status and get_order_timeline as the order advances. Verify the application displays the correct fulfillment state and customer-facing milestones. A timeline entry with time: null may be an upcoming milestone.
5. If your integration receives order callbacks, verify callback delivery and reconcile the received updates with the order status tools. Handle repeated callbacks without applying the same update twice.
6. Test quote expiry and cart changes by preparing a quote, allowing it to expire or editing the cart, then preparing a fresh quote and collecting new approval.
7. Verify uncertain-confirmation handling: retain the attempt and any known order ID, check the known order, and do not automatically create a replacement checkout after a timeout. Follow the recovery guidance above when an outcome cannot be established.

Use the scenarios available in the console to validate order progression. Order simulation does not establish coverage of every saved-card or payment-provider outcome; validate those payment cases separately. Keep sandbox and production configuration separate when moving to live ordering.