How do I use Cartroute from any function-calling framework?

Updated September 23, 2026 · API version 2026-09-01 · This page as JSON

Any framework that supports function calling can use Cartroute: register the JSON Schema below as a tool, and when the model calls it, send the arguments to GET /api/v1/search and return the JSON response as the tool result. The OpenAPI 3.1 description at /openapi.json can also be imported directly by frameworks that build tools from OpenAPI.

What is the portable tool definition?

This schema is framework-neutral. Most SDKs accept it as the tool's parameters object; some call the field parameters, others input_schema.

{
  "name": "search_products",
  "description": "Search 12 US retailers (Amazon, Walmart, Best Buy, Costco, Target and more) for a product. Returns every offer with price_usd, shipping_usd, best_coupon and effective_price_usd (price + shipping - best usable coupon). Rank offers on effective_price_usd. price_insight.verdict says whether today's price is a 90-day low. Costco and Sam's Club need a paid membership.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "What to find, in plain words. Budgets like \"under $400\" are understood."
      },
      "max_price": {
        "type": "number",
        "description": "Maximum effective price in USD."
      },
      "in_stock": {
        "type": "boolean",
        "description": "Only in-stock offers. Default true."
      },
      "include_membership": {
        "type": "boolean",
        "description": "Include Costco and Sam's Club. Default true."
      },
      "retailers": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "amazon",
            "bhphoto",
            "bestbuy",
            "costco",
            "lowes",
            "microcenter",
            "newegg",
            "samsclub",
            "staples",
            "target",
            "homedepot",
            "walmart"
          ]
        },
        "description": "Limit to these retailers."
      }
    },
    "required": [
      "query"
    ]
  }
}

What should the handler do?

import json
import os
import requests

def search_products(query, max_price=None, in_stock=True, include_membership=True, retailers=None):
    params = {"q": query, "limit": 3, "in_stock": str(in_stock).lower(),
              "include_membership": str(include_membership).lower()}
    if max_price is not None:
        params["max_price"] = max_price
    if retailers:
        params["retailers"] = ",".join(retailers)
    resp = requests.get(
        "https://cart-route.com/api/v1/search",
        params=params,
        headers={"Authorization": f"Bearer {os.environ['CARTROUTE_API_KEY']}"},
        timeout=20,
    )
    # Hand the body back either way: error bodies explain themselves to the model.
    return json.dumps(resp.json())

Which other tools are worth adding?

Tool	Endpoint	When the model should use it
`get_product`	`GET /products/{id}`	The user names an exact model, GTIN or a product from an earlier search.
`get_price_history`	`GET /products/{id}/price-history`	The user asks whether to buy now or wait.
`find_coupons`	`GET /coupons`	The user asks for codes at a specific store.

Is there a shortcut if my framework speaks MCP?

Yes. If the framework or runtime can connect to remote MCP servers, point it at https://cart-route.com/mcp and all seven tools arrive with their schemas, no handler code needed.