Nuvemshop

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

Retrieve schema information (available measures, dimensions, segments) for one or more Cube.js cubes. When to use: always call this before running any data query against a cube whose schema you have not already fetched this session — measure, dimension, and segment names are cube-specific, and querying with an unverified name produces a validation error rather than a helpful result. If you don't know the exact cube name, call list_cubes first. When NOT to use: this tool executes no data query and returns no rows or aggregates — it only describes what is queryable on the named cubes. Returns a simplified schema containing: - measures: Aggregations available (count, sum, avg, etc.) - dimensions: Fields to group by or filter on - segments: Pre-defined filters that can be applied Each member includes its name and description to help you understand what data is available and how to construct valid queries.

get_cube_schema

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

List the Cube.js cubes available for analytical queries. When to use: you do not know the exact name of the cube to pass to get_cube_schema, or you need to check which cubes exist. When NOT to use: this returns no measures, dimensions, segments, or data — only cube names and short metadata. Call get_cube_schema for the members of a cube, and query_stats for data. Returns every available cube, sorted by name, each with: - name: The exact cube name to pass to get_cube_schema - title: Human-readable title

list_cubes

Tool to retrieve customers from the store, with optional filters. When to use: the merchant asks about a customer directly — searching by name or email, browsing recent customers by signup date, or looking up a customer's contact info, address, or last-order number. Returns contact info (name, email, phone), default_address plus all shipping addresses (with country codes like AR, BR), billing address if available, total_spent, accepts_marketing, and last_order_number. When NOT to use: this tool returns customer records only — it never returns orders. It cannot search, filter, or list a customer's orders, and it exposes no order history: `last_order_number` is a single order number, not a list of past orders. A request phrased as "orders from customer X" is an order search, not a customer lookup, and does not need this tool at all. name and email are independent filters — combine them only if the merchant clearly means to require both. Example: list_customers(name="Juan Perez") to resolve a customer and read their contact details, addresses, total_spent, and last_order_number.

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 or a list of product IDs — not free-text search. When to use: fetching specific products by ID (e.g. "show me products 101 and 102"), or filtering by stock availability, price range, category, published status, brand, free shipping, missing shipping data, or creation/update date (e.g. "products with no stock", "unpublished products", "products under $5000", "products without a category", "products created this month"). 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. `product_ids` accepts 1 to 50 IDs and combines with every other filter (a product must match all of them). IDs that do not exist in the store are silently omitted. To spot missing IDs, compare the returned IDs with the requested ones — only when no other filter is set, since another filter can also exclude an existing product. Results are paginated — pass `page_size=50` to get up to 50 requested IDs in one page, and collect every page before comparing if the results span more than one. Several category IDs (`category_ids`) or brands (`brands`) match products in ANY of them; `category_ids` also combines with `category_id` the same way. Every other filter narrows the result (a product must match all of them). Date filters take `yyyy-MM-dd` (the start of that day, 00:00) or a timestamp such as `2025-01-31T23:59:59-03:00`; both bounds are inclusive, so use the next day or a full timestamp as `*_max` to include the last day. 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. Examples: - list_products(max_stock=0, fields_needed=["id"]) to find every out-of-stock product's ID for a bulk operation. - list_products(product_ids=[101, 102], fields_needed=["id", "name", "variant_stock"]) to read the name and stock of two known products. - list_products(has_categories=False, fields_needed=["id", "name"]) to find products that have no category assigned. - list_products(created_at_min="2025-01-01", created_at_max="2025-02-01", fields_needed=["id", "name"]) to find products created in January 2025.

list_products

Execute analytical queries against store data using the Cube.js query format. When to use: retrieving aggregated metrics (counts, sums, averages) grouped by dimensions, filtered, and/or broken down over time. When NOT to use: this returns rows inline and produces no file or download link. Before calling it, fetch the schema of any cube whose schema you have not already retrieved this session — measure, dimension, and segment names are cube-specific and not guessable. Query structure: - measures: Aggregations to calculate (e.g., "Orders.count", "Orders.totalAmount") - dimensions: Fields to group by (e.g., "Orders.status", "Orders.city") - filters: Conditions to filter data - time_dimensions: Time-based grouping and date ranges - segments: Pre-defined data segments to apply - order: Sort specification - limit/offset: Pagination controls Example measures: count, sum, avg, min, max Example filter operators: equals, notEquals, contains, gt, gte, lt, lte, set, notSet Example granularities: second, minute, hour, day, week, month, quarter, year Constraints: `limit` is capped at 35 (default 35), so this tool cannot return a larger result set in one call. On the `OrdersSummary` cube, sales/revenue measures (`gmv`, `avgTicket`) must always be paired with the `completedSales` segment — a `paidAt`-set filter alone is not equivalent, since it still counts fully-refunded orders as sales. Order-count measures (`distinctOrders`, `count`) are a separate, unfiltered mode and should not be combined with `completedSales` or payment-status filters. `reasoning` is required on every call and must justify the query, name the specific measures/dimensions chosen, and confirm the call is not a duplicate of a prior query this turn. Returns query results as a list of data rows with the requested measures and dimensions.

query_stats

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

Update an existing coupon, identified by its current code. When to use: changing a coupon's value, dates, restrictions, or active status (set valid=false to deactivate, true to reactivate) — including deactivating a coupon straight after creating it, which is the only way to end up with an inactive coupon. When NOT to use: this updates a coupon in place and never removes it. Setting valid=false deactivates it reversibly; it stays in the store's coupon list. Constraints: only the provided fields are updated; omitted fields remain unchanged. products must be product IDs, not variant IDs — a product can have several variants, each with its own distinct ID, and variant IDs are rejected. Example: update_coupon(code="SUMMER2026", valid=False) to deactivate.

update_coupon

Update an existing product in the store catalog, including its variants and images. When to use: changing any field of a product that already exists — name, description, published status, SEO fields, tags, categories, attributes, variants, or images. Only the fields provided are modified; omitted fields remain unchanged. When NOT to use: this tool edits products only, one product per call. `product_id` must be a product id — a category id is a different identifier and is never valid here, even though both are integers. This tool cannot edit a category itself: renaming, reparenting, or reordering a category is not available through the API at all, and belongs in the admin UI. Requires the product_id of the product to update. 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'. - Promotional (sale) price: set 'promotional_price' lower than the variant's regular price; send "0" to remove it. null or omitted leaves it unchanged. A promo that is not lower than the regular price rejects the whole call. 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

Update an existing promotion, identified by its promotion_id. When to use: changing a promotion's discount value, scope, dates, or active status (published=false to deactivate, true to reactivate). When NOT to use: this updates a promotion in place and never removes it. Setting published=false deactivates it reversibly; the promotion itself remains. Constraints: - Updating discount_value requires promotion_type to also be provided in the same call — the backend needs both to apply the value correctly. - Providing begin_date/end_date sets date limits; omitting them on a promotion that previously had dates clears those dates rather than leaving them unchanged. - scope_value, when provided, must match scope_type (product IDs or category IDs, already resolved — this tool does not resolve names to IDs). Changes take effect immediately on qualifying purchases. Example: update_promotion(promotion_id=4321, published=False) to deactivate.

update_promotion

Bulk update stock levels, prices and/or promotional (sale) prices for product variants. When to use: changing price, promotional_price, stock, or any mix of them for one or more variants — this is the bulk tool for stock and prices on existing products. Promotional price: the sale price buyers see instead of the regular one. It must be lower than the regular price (the 'price' in the same item, or the variant's current price). Send promotional_price: '0' to remove a sale price; null or omitted leaves it unchanged, so null never removes it. An item with a promotional_price that is not lower than the regular price is not applied and comes back with success: false and an 'error'; the other items still run. When NOT to use: for cost, sku, barcode, or mpn — these fields are not supported by this tool and either cause a validation error or are silently ignored; there is currently no tool that edits them on an existing product. Each update targets a specific variant by product_id and variant_id. Constraints: maximum 50 variant updates per request. Variant IDs are required — use search_products or list_products first to discover them; product IDs alone are not enough. Each update must include at least one of price, promotional_price or stock (an all-null update is a validation error). Price and stock changes are immediately visible to buyers on the live storefront. Example: update_stock_and_price(updates=[{'product_id': 42, 'variant_id': 1001, 'price': '29.99', 'stock': 10}, {'product_id': 42, 'variant_id': 1002, 'promotional_price': '19.99'}]).

update_stock_and_price