VTEX

Get order counts across different time periods: today (current day orders), yesterday (previous day orders), lastWeek (same day last week orders), lastMonth (same day last month orders), lastYear (same day last year orders). Note: This tool provides pre-calculated counts for specific time periods and does not use date range parameters. The "lastYear" count refers to the same day of the year in the previous year, not a 90-day range. Timezone parameter is optional and defaults to EST (-5). Use this for quick time-based comparisons without date range limitations.

Returns INDIVIDUAL ORDER RECORDS with full details for REVENUE-GENERATING ORDERS. By DEFAULT filters for revenue orders only: "payment-approved,ready-for-handling,handling,invoiced". Use when you need: specific order information, customer details, order tracking for completed sales. NOT for aggregated metrics or business analysis. Supports full-text search, datetime formats (YYYY-MM-DDTHH:MM:SS), timezone conversion, status filtering, and all VTEX OMS filter parameters. Common usage patterns: • Revenue orders (default): automatically includes only orders that count as sales • All statuses: set f_status="" to include all order statuses (canceled, payment-pending, etc.) • Specific status: use "f_status" to override default (e.g., "canceled", "payment-pending") • Full-text search: use "q" parameter (searches order ID, client name, email) • Date range: use "startDate" and "endDate" with optional "timezone" (e.g., "America/Bogota") • Recent orders: call without filters for latest revenue orders Each query retrieves up to 90 days of orders. For longer periods (e.g., annual order analysis), make multiple calls with consecutive 90-day ranges. Returns paginated data as JSON tuples for token efficiency. Response includes pagination metadata: ["meta", "type", "paginated_data"], ["meta", "currentPage", N], ["meta", "totalPages", N], ["meta", "totalOrders", N], ["meta", "hasMoreData", 0/1]. Each order tuple contains: [orderId, creationEpoch, clientName, totalValue, paymentNames, status, salesChannel, origin]. Use "page" parameter to navigate through results when hasMoreData=1.

Returns AGGREGATED METRICS and counts (totals, averages, summaries). Use when you need: totals by category, comparative analysis, business intelligence. NOT for individual order details. Perfect for both simple counts and complex business intelligence with datetime formats (YYYY-MM-DDTHH:MM:SS) and timezone support. Key use cases: • Basic Counts & Metrics: Count orders by any filter (payment method, status, date range, etc.), get totals for revenue and orders across any dimension, answer questions like "how many PSE orders?" or "how many canceled orders?" • Comparative Analysis: Compare performance between payment methods, channels, sellers, analyze customer behavior patterns across segments, identify growth/decline trends by category • Business Intelligence: Strategic insights for decision-making and performance monitoring, campaign and promotion effectiveness analysis, operational KPI tracking and benchmarking Each query aggregates up to 90 days of data. For longer analysis (e.g., yearly payment method trends), make multiple calls with consecutive 90-day ranges. Returns complete aggregated data in [category, dimension, value, count] format optimized for token efficiency. Response includes metadata: ["meta", "type", "aggregated_data"], ["meta", "totalFacetGroups", N], ["meta", "totalItems", N], ["meta", "isPaginated", 0]. Key distinction: Provides aggregated insights vs. search_orders which returns individual records.

Ranks and compares performance within business dimensions (brands, categories, products, payment methods, etc.). Shows top/bottom performers with period-over-period growth analysis. Perfect for questions like "which are my top-selling brands?" or "what products are declining?" Key use cases: • Performance ranking: Find top-selling brands, categories, or products by revenue/orders • Growth analysis: Identify fastest growing/declining items with period-over-period comparisons • Competitive insights: Compare performance between different items within the same dimension • Trend identification: Spot emerging opportunities or declining segments Each query analyzes up to 90 days. For longer periods (e.g., 2-year brand analysis), make multiple calls with consecutive 90-day ranges. OPTIONAL: Call get_filter_options first if you need to discover available filter values for accurate filtering. Returns ranked lists with growth metrics as [itemName, metricName, currentValue, previousValue, percentChange] tuples. Response includes pagination metadata: ["meta", "totalItems", N], ["meta", "returnedItems", N], ["meta", "hasMoreData", 0/1], ["meta", "estimatedPages", N]. Use "itemsPerPage" parameter to control results. When hasMoreData=1, increase itemsPerPage or apply filters to get more specific results. Essential for performance benchmarking and competitive analysis.

Discovers available filter values for any business dimension (brands, categories, products, payment methods, etc.). Essential prerequisite for accurate filtering in other analytics tools. Use this when you need exact filter values for filtering in breakdown_metrics_by_dimension. Key use cases: • Find exact names: Get precise spelling/format of brands, categories, or products • Explore catalog: Discover what dimensions exist in your data (e.g., find all payment methods) • Validate filters: Ensure filter values exist before using in other analytics tools • Data discovery: Understand available segments for analysis Each query analyzes up to 90 days. For longer periods, make multiple calls with consecutive 90-day ranges. Returns complete dimension data as [optionValue, optionId] tuples. Response includes metadata: ["meta", "type", "dimension_options"], ["meta", "totalOptions", N], ["meta", "isPaginated", 0]. This provides complete data for the specified dimension and date range.

Retrieves conversion rate data over time with period-over-period comparisons. Shows how website conversion performance changes across different time periods. Essential for measuring campaign impact and identifying conversion patterns. Key use cases: • Performance monitoring: Track daily/weekly conversion rate changes • Campaign impact: Measure conversion rate before/during/after campaigns • Trend analysis: Identify conversion rate patterns and seasonal effects • Benchmarking: Compare current performance vs historical periods Each query analyzes up to 90 days. For longer trend analysis (e.g., yearly patterns), make multiple calls with consecutive 90-day ranges. Aggregation parameter controls data grouping: "hour" for hourly data points, "day" for daily summaries, "week" for weekly summaries. Returns overall conversion rates plus time-series data showing trends. Data format: [referenceEpoch, comparedEpoch, currentRate, previousRate, percentChange] tuples.

Get comprehensive business health snapshot with all key metrics (revenue, orders, AOV, conversion rate, sessions) in a single call. Perfect for executive dashboards and quick performance checks. Provides complete store performance overview with period-over-period comparisons. Key use cases: • Executive dashboards: Get all key KPIs in one call • Performance monitoring: Track overall business health metrics • Quick diagnostics: Answer questions like "What's our AOV?" or "How are we performing?" • Trend analysis: See if key metrics are improving or declining • Business reporting: Get formatted data for reports and presentations Each query analyzes up to 90 days. For longer performance tracking (e.g., quarterly reports), make multiple calls with consecutive 90-day ranges. Aggregation parameter controls data grouping: "hour" for hourly data points, "day" for daily summaries, "week" for weekly summaries. Returns structured JSON with current values, previous period values, and percentage changes for each metric. Includes revenue, order count, average order value, sessions, and calculated conversion rate.

Retrieve paginated list of brands from the VTEX store catalog. Perfect for browsing available brands, analyzing brand portfolio, or finding specific brand information. Key use cases: • Brand discovery: Find all available brands in the store • Brand analysis: Check which brands are active vs inactive • Brand validation: Verify if a specific brand exists in the catalog • Inventory planning: Review brand portfolio for merchandising decisions No date range limitations - provides static catalog data. Returns data as JSON tuples for token efficiency. First tuple contains pagination info: ["paging", currentPage, totalPages, totalBrands]. Each brand tuple contains: [brandId, brandName, isActive]. Default page size is 30 brands. Use pagination to browse through large brand catalogs efficiently.

Retrieve the category tree structure from the VTEX store catalog. Perfect for understanding product categorization, building navigation menus, or analyzing category hierarchy. Key use cases: • Category discovery: Explore the complete category structure • Navigation building: Generate menu structures for storefronts • Category analysis: Understand how products are organized • Inventory planning: Review category coverage and gaps No date range limitations - provides static catalog data. Specify categoryLevels to control tree depth (default: 3 levels, max: 3). Returns data as JSON tuples for token efficiency. Each category tuple contains: [level, categoryId, categoryName, hasChildren, childrenCount]. Child categories are included as nested tuples with increasing level numbers.