Ciruelo Home

• Search Products — Tool to search for products in the store catalog. Uses regular and semantic search to find products matching the query. Try with different synonyms and different queries for broader results.
• Get Cart — Retrieve the current contents of a cart, including all items and the checkout URL. When to use: displaying or processing a customer's cart in the storefront or checkout flow, given its cart_id and cart_hash. When NOT to use: this tool is read-only — it adds, removes or changes nothing in the cart. Constraints: cart_hash must be the exact 40-character hexadecimal SHA1 hash returned when the cart was created or retrieved; a malformed hash is rejected before the cart lookup happens.
• Update Cart — Update the items in an existing cart, add new items, or remove items by setting quantity to 0. Creates a new cart if no cart_id is provided. When to use: any add/remove/change-quantity operation on the storefront cart. When NOT to use: this tool always writes. It is not a read-only inspection of the cart, and with no cart_id it creates a new cart rather than reporting an existing one. Constraints: cart_hash is required when cart_id is provided (updating an existing cart), and must be the exact 4
• Get Shipping Methods — Get shipping methods and options for a store — either the store's general configuration, or real shipping costs/delivery estimates for a specific cart. When to use: called with no parameters, for the general list of shipping methods and pickup points configured in the store; called with cart_id, cart_hash, and zipcode together, for calculated shipping costs and delivery estimates for that cart's contents to a specific destination. When NOT to use: zipcode alone, without
• Get Promotions — Get all active promotions in the store — product-specific, category-specific, and store-wide, including free shipping ones. When to use: a general overview of every active promotion, regardless of type. When NOT to use: this is an unfiltered overview. It takes no parameters, so it cannot narrow results to specific products, and it does not expand free-shipping conditions (minimum purchase, applicable categories, shipping methods) — those details are not in this response
• Get Free Shipping Promotions — Get free shipping promotions with their shipping conditions, minimum purchase requirements, applicable categories, and shipping methods. When to use: the request is specifically about free shipping — e.g. checking minimum purchase thresholds or which categories qualify. When NOT to use: this returns free-shipping promotions only. Percentage, absolute, and buy-X-pay-Y promotions are not included, so it is not a view of every active promotion. Returns up to 20 free s
• Get Payment Methods — Retrieve available payment methods for the store — either the store's general configuration, or the methods specific to one cart. When to use: called without cart_id, for the store's general payment methods; called with cart_id and cart_hash together, for the methods applicable to that specific cart. When NOT to use: method_type filtering only applies when cart_id is NOT provided — passing both has no effect on the cart-scoped result. Constraints: cart_id requires
• Track Order — Get tracking information for one order, verified against the customer's email. When to use: the caller already has an order number and the purchasing customer's email — tracking status, status page URL, tracking code/URL, estimated delivery, or pickup location for that one order. When NOT to use: this tool cannot search or browse. It accepts only an exact order number plus the matching customer email; partial, fuzzy, and criteria-based lookups are unsupported. Cons

Schemas and invoke metadata: Directory API