TiendaNube

Get full details of one coupon by its code — discount type, value, usage statistics, restrictions, and date range. When to use: the coupon code is already known (e.g. "is VERANO2026 still active?", "what are BIENVENIDO's conditions?"). When NOT to use: this requires the exact, complete coupon code. It performs no partial matching and takes no filters, so it cannot search or browse. Example: get_coupon_details(code="SUPERCOUPON15").

get_coupon_details

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 shipping promotions.

get_free_shipping_promotions

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 cart_hash to also be provided — passing one without the other raises a validation error. 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. Parameters: - cart_id: ID of the cart (requires cart_hash when provided) - cart_hash: Hash of the cart for validation (required when cart_id is provided) - method_type: Filter by specific payment method type - language: Language for payment method names - billing_country: Billing country to filter available methods IMPORTANT: When getting payment methods for a cart, both cart_id and cart_hash are required.

get_payment_methods

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. Returns up to 50 promotions in a simple, organized format.

get_promotions

Get promotions applicable to a specific set of products (either promotions scoped directly to those products, or general store-wide promotions). When to use: the caller already knows which products it cares about — e.g. items in a cart, or a product being viewed — and wants only the promotions relevant to them. When NOT to use: this requires product_ids — it cannot return the store's promotions in general, and it does not resolve product names to ids. Constraints: `limit` has no default and must always be passed explicitly (1-20).

get_promotions_by_products

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 cart_id and cart_hash, is not a supported combination and raises a validation error — this tool only calculates real shipping costs in the context of a specific cart. Constraints: cart_id requires both cart_hash and zipcode to be provided together — providing cart_id without either of the other two raises a validation error. cart_hash alone, without cart_id, is not validated or used — it is silently ignored and the call falls back to the general shipping-methods response, so always pass cart_id together with cart_hash. cart_hash must be the exact hash returned when the cart was created or retrieved, in the 40-character hexadecimal SHA1 format; a malformed hash is rejected before the cart lookup happens. Parameters: - cart_id: ID of the cart (requires cart_hash and zipcode) - cart_hash: Hash of the cart for validation (required when cart_id is provided) - zipcode: Destination postal code (required when cart_id is provided) - country_code: Country code for international shipping (optional, defaults to store country) IMPORTANT: When calculating shipping for a cart, you MUST ask the user for their zipcode if not provided. Do not assume or invent zipcodes.

get_shipping_methods

List all categories in the store catalog with their hierarchy (subcategories). When to use: discovering the category tree, and resolving a category name to its numeric ID — merchants refer to categories by name, never by ID, so any category id needed elsewhere is resolved here first. When NOT to use: this tool returns categories only. It lists no products and accepts no product filters, so it cannot tell you which products belong to a category. Returns every category with its parent/child hierarchy in one call — there is no pagination or filtering.

list_categories

List and search discount coupons — promotional codes customers apply at checkout, as opposed to promotions, which apply automatically with no code. When to use: browsing or searching coupons by code, validity, activation status, discount type, or shipping applicability. When NOT to use: this returns coupons only — automatically-applied promotions, which need no code, are a separate concept and never appear here. It also returns a paginated summary per coupon rather than one coupon's full detail. Returns coupons with their codes, discount information, and any applicable conditions or restrictions, paginated (default 50 per page, max 100).

list_coupons

Tool to retrieve customers from the store. Use cases: - Search customers by name, email, or identification - View recent customers by filtering with created_at_min/max - Browse customers with pagination Returns customers with: - Contact info: name, email, phone, cpf_cnpj (identification) - Addresses: default_address and all shipping addresses with country codes (AR, BR, etc.) - Billing info: billing address details if available - Metadata: total_spent (in store currency), accepts_marketing - Order history: last_order_number (use with list_orders order_number filter)

list_customers

Tool to retrieve a list of orders for the store, with optional filters. When to use: the merchant asks about existing orders — showing all orders, searching for a specific order, or narrowing results by status, fulfillment status, payment status, customer, product, shipping option, date range, or unit count. Returns order number, status, line items, and total amount for each matching order. When NOT to use: this tool returns orders only. It does not return a customer's contact info, addresses, or lifetime order history on their own, and it does not enumerate the store's shipping methods — `shipping_options` filters by method/option codes that must already be known, it cannot list the valid values. Filter priority when multiple identifying filters are given: order_number takes priority over customer_email, which takes priority over customer_name, which takes priority over total. Only one of these four should be used per call; combine the others (status, dates, units, products_filter, shipping_options) freely. Constraints: `order_number`, when provided, must be >= 100. `customer_email`, when provided, must be a syntactically valid email address. `page`, `limit`, `min_units`, and `max_units`, when provided, must all be >= 1. An invalid value in any of these raises a validation error instead of running the search — do not retry with the same value; ask the merchant for a corrected one. Example: find open orders shipped with a specific carrier method — list_orders(status=["open"], shipping_options=[{"methods": ["api_1459801"]}]).

list_orders

List and filter products from the store catalog using structured attribute filters — not free-text search. When to use: filtering by stock availability, price range, category, published status, brand, or free shipping (e.g. "products with no stock", "unpublished products", "products under $5000"). When NOT to use: this tool performs no text matching at all. A free-text query or product name (e.g. "blue t-shirt", "do you have Casio watches?") cannot be passed here — every filter below matches an exact attribute value, never a name fragment. Constraints: `page` defaults to 1, `page_size` defaults to 20 and is capped at 50. When collecting product IDs to feed a later bulk operation, pass `fields_needed=["id"]` — including `"variants"` or `"description"` multiplies response size 10-100x and can exhaust a caller's context budget for no benefit when only IDs are needed. Example: list_products(max_stock=0, fields_needed=["id"]) to find every out-of-stock product's ID for a bulk operation.

list_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.

search_products

Show or hide a category in the storefront menu. When to use: toggling whether a category appears in storefront navigation. When NOT to use: this only flips the visible/hidden toggle — it never edits a category's name, parent, or any other field. There is no third "soft-hidden" state. Resolving the target: - Merchants say "hide the Clothing category", never a numeric ID. Call `list_categories` first to resolve the name to an ID; disambiguate with the merchant if multiple matches exist. Semantics: - Hiding is a "hide from navigation" toggle, not a deletion. URLs still work. Cascade behavior (from the catalog backend): - Hiding a category ALSO hides all its subcategories recursively. - Showing a category ALSO shows all its subcategories. - A child cannot be shown while its parent is hidden; if asked to show a child first, point out that the parent must be shown too. Constraint: - This tool only exposes the visible/hidden toggle; it never writes the soft-hidden state. Changes take effect immediately in the live storefront navigation.

update_category_visibility

Tool to update an existing coupon identified by its code. Modifies coupon properties such as value, dates, status, and restrictions. Also used to deactivate a coupon by setting valid to false. Use cases: - "Change the SUMMER2026 coupon to 25%% off" - "Disable coupon OLDPROMO" - "Extend the BIENVENIDO coupon until June" - "Update the minimum purchase for ZAPATOS20 to $100" Only the provided fields are updated; omitted fields remain unchanged. Changes take effect immediately for customers at checkout.

update_coupon

Tool to update an existing product in the store catalog, including its variants and images. Requires the product_id of the product to update. Only the fields provided will be modified; omitted fields remain unchanged. Warning: if 'categories' is sent as an empty list, the product will lose all its categories. Updatable product fields: - name, description, published, free_shipping, requires_shipping, brand - seo_title, seo_description, tags, categories, attributes, video_url Variant management (via 'variants' list): - Create: omit 'id', provide 'price' (required) and 'values' matching product attributes. - Update: provide 'id' plus fields to change. - Delete: provide 'id' and 'delete: true'. Image management (via 'images' list): - Each image requires 'src' (URL). Always include 'alt' together with 'src'. If published is changed to true, the product becomes immediately visible to buyers on the live storefront.

update_product

Publish or unpublish one or more products in the store catalog. When to use: making one or more known product IDs visible or hidden on the storefront in a single call. When NOT to use: this tool only toggles the published flag. It writes no other product field — not price, stock, name, or anything else — and it takes no per-product values, only one published value for the whole batch. Set published=true to make products visible, or false to hide them. Constraints: maximum 20 product IDs per request; product IDs must come from a prior search_products or list_products call. Changes take effect immediately on the live storefront, directly affecting what buyers can see and purchase. Example: update_visibility(product_ids=[101, 102], published=False).

update_visibility

Tool to update an existing promotion in the store. Modifies promotion properties such as discount value, scope, dates, and status. Also used to activate or deactivate a promotion by setting published to true or false. Use cases: - "Change the summer promotion to 25% off" - "Deactivate promotion 12345" - "Extend the electronics promotion until June" - "Change the promotion scope to specific categories" Set published=false to deactivate, published=true to reactivate. Warning: providing begin_date/end_date sets date limits on the promotion. Omitting dates on an update that previously had dates will clear them. Changes take effect immediately on qualifying purchases.

update_promotion

Bulk update stock levels and/or prices for product variants. Each update targets a specific variant by product_id and variant_id. You can update price, stock, or both in a single call. Maximum 50 variant updates per request. Variant IDs are required — use search_products or list_products first to discover them. Price and stock changes are immediately visible to buyers on the live storefront.

update_stock_and_price