Razorpay ACE Marketplace

Add a product to the shopping cart. IMPORTANT: productId must be the `id` field from product-search results. If cartId is omitted, a new cart is created — its ID is returned in the response. Pass this cartId to all subsequent cart operations. A cartId the store does not know → errorCode CART_NOT_FOUND; a productId from another store → PRODUCT_NOT_FOUND. If the store accepts fewer units than requested the response carries requestedQuantity / appliedQuantity / reason; lineQuantity is what the line now holds. Each product is capped per order at the store's purchase limit (else stock, else 25): over it → MAX_UNITS_PER_ITEM_EXCEEDED with limit. A product the store does not sell online → NOT_SELLABLE_ONLINE. A non-integer or < 1 quantity → VALIDATION. One store: `merchants: "<key>"` + top-level fields; several: `merchant_args: { "<key>": { ...fields } }`. Flat cart: cart.lines[], subtotal, total; rupees (amountUnit:'major'). cartId optional with Mcp-Session-Id.

add_to_cart

Remove all items from the cart. One store: `merchants: "<key>"` + top-level fields; several: `merchant_args: { "<key>": { ...fields } }`. cartId optional with Mcp-Session-Id.

clear_cart

Create a REAL, payable Razorpay order and return a hosted checkout_url. Call once, after the shopper agrees. Args: { cartId } (from add_to_cart, full id incl. ?key=) OR { cartItems: [{productId|variantId, quantity}] }; optional pincode (6 digits, delivery check), idempotencyKey (8-128 chars; same key returns the same order). Reuse: a repeat on the same unchanged cart (or key) within 15 minutes returns that order with reused:true; a changed cart, or a call after that, mints a new order. Razorpay cannot cancel an unpaid order. total_amount is paise (total_amount_unit:'minor'); amount_display is human. Swiggy/Instamart/Dineout place real orders: without the shopper's yes they return CONSENT_REQUIRED; ask, then resend with notes.paymentMethod:'upi'. Error codes: see the usage guide. One store: `merchants: "<key>"` + top-level fields; several: `merchant_args: { "<key>": { ...fields } }`. checkout_url valid until expires_at or a cart change; several stores: report each of `checkout.orders[]` / `failed[]`. cartId optional with Mcp-Session-Id.

create_checkout

Get the filter values (categories, brands, tags, sizes, colors, price range) valid for a product query at the store. Call it with the shopper's query before search_products when they mention a brand, category, size, color or other attribute. WORKFLOW: 1. User mentions a filter (brand/category/size/color/tags) — call this tool first, with `query`. 2. Use the exact `value` strings from the response. 3. Call search_products with the same query and those exact filter values. 4. Always follow this tool with a search_products call — never stop here. RETURNS (facets are computed from the products matching `query`; `basedOn.sampleSize` says how many): - productTypes: [{label, value, count}] — pass `value` as search_products.productType - vendors: [{label, value, count}] — pass `value` as search_products.vendor - tags: [{label, value, count}] — pass `value` in search_products.tags - priceRange: {min, max, currency} or null when unknown - variantOptions: [{name, values: [{value, count}]}] — e.g. {name: 'Size', values: [{value: 'M'}]} EXAMPLES: 'show me nike shoes' → get_filter_options({query: 'shoes'}), then search_products({query: 'shoes', vendor: 'Nike'}) 'blue t-shirts on sale' → get_filter_options({query: 't-shirts'}), then search_products({query: 't-shirts', tags: ['sale'], variantOptions: [{name: 'Color', value: 'Blue'}]}) Multi-store: omit `merchants` to auto-select stores; pass key(s) only when the shopper names a store. Results under `merchants.<key>`; those keys are the store keys for cart/checkout.

get_filter_options

Get payment status for a Razorpay order. Pass `razorpay_order_id` (the `order_id` returned by create_checkout, 'order_' + 14 letters/digits). Returns found:true with order_status, payment_status (paid/pending), amount / amount_paid / amount_due in rupees (amountUnit:'major'; *_paise in paise), currency, payments and line_items [{name, quantity, unit_price, line_total}] in rupees (filled for Magic Checkout orders, which create_checkout makes; else [] with line_items_note); found:false with errorCode NOT_FOUND for an id this store does not own, or VALIDATION for a malformed id. It does NOT return the shipping address or fulfillment/shipment status. One store: `merchants: "<key>"` + top-level fields; several: `merchant_args: { "<key>": { ...fields } }`.

get_order_status

Show detailed information for a specific product. Use this tool when the user wants to see more details about a single product, view product images, or check available variants (sizes, colors). Pass the `id` from search results as productId (Shopify: a Product or ProductVariant gid, or the handle; Fynd: the numeric id or the slug). Returns price, compareAtPrice, currency, brand, url, inStock, variants[] and a plain-text return policy; `serviceability` only with pincode, `sizePrice` only with variantId. An unknown id returns errorCode PRODUCT_NOT_FOUND. One store: `merchants: "<key>"` + top-level fields; several: `merchant_args: { "<key>": { ...fields } }`.

get_product_details

List the stores this server can search, a page at a time. Returns key, storeName, platform, what the store sells, and health ('healthy' = answered recently, 'unknown' = not checked yet, 'degraded', or 'open' when the store is being skipped, with reason and retryAfter). Filter with platform, category (e.g. 'skin care', 'smartwatches') and health; page with limit and the returned nextCursor. Use `key` as the store key for `merchants` and `merchant_args` on every other tool. Stores that cannot be routed to are not listed.

list_merchants

Remove a product from the cart. Args: {cartId, productId | lineId, quantity?}. Without quantity the whole line is removed; with quantity it is reduced by that many (the line goes when it reaches 0). Identify the line by productId (variant id from search) OR lineId (from view_cart). Unknown cart → errorCode CART_NOT_FOUND; line not in cart → LINE_NOT_FOUND. One store: `merchants: "<key>"` + top-level fields; several: `merchant_args: { "<key>": { ...fields } }`. cartId optional with Mcp-Session-Id.

remove_from_cart

Primary tool for showing products to users. Use this tool when the user wants to find, browse, search, or see products. Returns product results as plain text and structured data. SEARCH BEHAVIOR (matches Shopify website): - Full-text search across title, description, tags, AND variant option values (Color, Size, etc.) - Color/size keywords in query are auto-extracted to variantOptions for facet filtering - Example: 'blue tshirt' → query='tshirt' + variantOptions=[{name:'Color', value:'Blue'}] - Each store's result includes availableFilters (top category, brand, tag and option values, price range); call get_filter_options for the full lists FILTER USAGE RULES: 1. Apply every filter the user mentions: price, brand, category, size, color, or other attributes. 2. For price filters: extract numbers from user input (e.g., 'under 20000' → maxPrice: 20000). 3. For brand/category/tag/variant filters: call get_filter_options first to get valid values. EXAMPLES: - 'phones under 20000' → {query: 'phones', maxPrice: 20000} - 'nike shoes size 10' → call get_filter_options, then {query: 'nike shoes size 10'} — auto-extracts Size:10 - 'blue jeans 2000 to 5000' → call get_filter_options, then {query: 'blue jeans', minPrice: 2000, maxPrice: 5000} PHONE NUMBERS (recharge): put the digits in `query`, e.g. {query: '9876543210 long validity'}; there is no phone field. Multi-store: omit `merchants` to auto-select stores; pass key(s) only when the shopper names a store. Results under `merchants.<key>`; those keys are the store keys for cart/checkout.

search_products

Set the absolute quantity of one cart line. Args: {cartId, productId | lineId, quantity}; quantity 0 removes. If the store accepts fewer units (purchase limit / stock) the response is still success:true and carries requestedQuantity, appliedQuantity and reason — tell the shopper the applied quantity. Above the product's per-order cap (store purchase limit, else stock, else 25) → MAX_UNITS_PER_ITEM_EXCEEDED with limit, nothing changed. One store: `merchants: "<key>"` + top-level fields; several: `merchant_args: { "<key>": { ...fields } }`. cartId optional with Mcp-Session-Id.

update_cart_item