calculateDateEpoch
ChatGPTConvert between human-readable dates and Unix epoch timestamps, generate date ranges for reports, and create comparison periods. Supports various timezones and predefined periods. Important: Always use this tool to get the most accurate timestamp for 'from' and 'to' date calculation before any tool for retrieving reports
createGroup
ChatGPTCreate a new custom product group for a merchant store. What it does: Creates a named group and optionally seeds it with an initial list of products (by sellerSku). Groups organize products for analytics. Group names must be unique per store. For brand-based groups use createGroupByBrands instead. When to use this tool — example user queries: - "create a group called Summer Products on store X" - "make a new product group with SKUs A, B, C" - "set up a custom group for my top sellers" - "add a group named Seasonal Items to my Amazon store" Routing & params: - channelId, merchantId: required — use getChannels tool first to retrieve valid values. - groupName: required — unique name for this store; blank names are rejected. - products: optional list of {sellerSku} items to add at creation time.
createGroupByBrands
ChatGPTCreate a new custom brand group for a merchant store. What it does: Creates a brand-filtered group from a list of brand name strings. Brand groups differ from product groups — they aggregate by brand rather than by SKU. Use updateGroup to rename or modify brand membership. For SKU-based groups use createGroup instead. When to use this tool — example user queries: - "create a group for all Nike and Adidas products" - "make a brand group called Sports Brands with Nike, Adidas, Puma" - "group all my Nike products together by brand" - "create a brand-based group on store X" Routing & params: - channelId, merchantId: required — use getChannels tool first to retrieve valid values. - groupName: required — unique name for this store. - brands: required non-empty list of brand name strings.
deleteGroup
ChatGPTDelete a custom group from a merchant store. Permanent and irreversible. What it does: Permanently removes the group and all its product/brand assignments. The group no longer appears in analytics tools. This cannot be undone. When to use this tool — example user queries: - "delete the group called Summer Products" - "remove the test group from store X" - "I want to delete group ID 42 named Old Campaign" - "clean up the unused groups on my store" Routing & params: - channelId, merchantId: required — use getChannels tool first to retrieve valid values. - groupId: required integer — from getCustomGroups. - confirmGroupName: required — the exact group name as returned by getCustomGroups. The server cross-checks this against the groupId before issuing the delete; a mismatch returns an error without deleting anything. Always call getCustomGroups first to obtain the exact name and groupId. - confirm: omit on the first call; re-call with confirm: true to proceed.
generateReport
ChatGPTGenerate any type of report for a channel and merchant. Use getChannels tool first to retrieve valid channelId and merchantId values. Use the report_type parameter to select the report: - campaigns: Advertising campaigns performance - cancellationsAndRefunds: Order cancellations and refund metrics - channelProfitAndLoss: Channel-level profit and loss statement. Single-window: the CSV always covers the requested fromDate/toDate only, so priorFromDate/priorToDate are ignored. Defaults to settled (cash-basis) figures — pass profitabilityView: 'accrual' to reconcile against order-date sales data. - customerLifetimeValue: Customer lifetime value analysis - inventoryHealth: Inventory health and stock levels (Amazon vendor channels only) - inventoryReplenishment: Inventory replenishment recommendations (Amazon seller channels only; no date range required) - marketingByProduct: Marketing spend and performance broken down by product - orderedRevenue: Vendor ordered revenue (Amazon vendor channels only) - products: Product catalogue details — Enterprise only (requires skus[], no date range) - repeatPurchase: Repeat purchase rate and customer retention - salesByProduct: Sales metrics broken down by product - shippedRevenue: Vendor shipped revenue (Amazon vendor channels only; requires view: shipping|manufacturing) - subscribeAndSave: Subscribe & Save subscription metrics - suppressedProduct: Suppressed product listings (no date range required) - trafficAndConversion: Traffic and conversion rate metrics (requires view: 'parents'|'skus') - amazonBuyBoxPerformance: Amazon Buy Box performance (requires filter, no date range) A channelProfitAndLoss report always covers the requested fromDate/toDate window only; priorFromDate/priorToDate are not sent for it and no comparison window appears in the file. After generating a report, use getReportStatus to poll for completion and retrieve the download URL. Then use readSummarizedReport to analyse the downloaded report.
getAdvertisingAdGroups
ChatGPTList advertising ad group performance across one or more channels. What it does: Returns ad-group-level advertising performance (impressions, clicks, cost, attributed sales, ACOS, ROAS, etc.) for the given channels and date range, optionally scoped to specific campaigns. When to use this tool — example user queries: - "list the ad groups under campaign 10012" - "what ad groups are running on my store this month?" Routing & params: - channelId: required — use getChannels tool first to retrieve valid values (1-5 channels). Skip any channel with 'hasAdvertisingConnected: false' — it has no advertising connection and this tool will reject it. - fromDate, toDate: required, unix epoch seconds. Server enforces a maximum date range of 6 months. - campaignId: optional — filter to specific campaign IDs (up to 10). Use getAdvertisingCampaigns first to find IDs. - pageIndex, pageSize, sortKey, sortOrder, currency, status: optional refinements.
getAdvertisingByChannels
ChatGPTRetrieve advertising performance metrics for all channels with configurable reporting periods and comparison analysis. Supports filtering, pagination, sorting, and returns time-based advertising data with current vs prior period comparisons. Returns direct JSON data without AI summarization. Each period (fromDate to toDate, and priorFromDate to priorToDate) may cover at most 31 calendar days in the report timezone, so one full calendar month fits in one call.
getAdvertisingCampaigns
ChatGPTList advertising campaign performance across one or more channels. What it does: Returns campaign-level advertising performance (impressions, clicks, cost, attributed sales, ACOS, ROAS, etc.) for the given channels and date range, merged across channels into a single paginated list. When to use this tool — example user queries: - "show me my ad campaigns for the last 30 days" - "what's the ACOS on my campaigns this month?" - "list active campaigns for my Amazon store" Routing & params: - channelId: required — use getChannels tool first to retrieve valid values (1-5 channels). Skip any channel with 'hasAdvertisingConnected: false' — it has no advertising connection and this tool will reject it. - fromDate, toDate: required, unix epoch seconds. Server enforces a maximum date range of 6 months. - groupId: optional — filter by custom campaign group IDs (from getCustomGroups). - pageIndex, pageSize, sortKey, sortOrder, currency, status: optional refinements.
getAdvertisingKeywords
ChatGPTList advertising keyword performance across one or more channels. What it does: Returns keyword-level advertising performance (impressions, clicks, cost, attributed sales, ACOS, ROAS, etc.) for the given channels and date range, optionally scoped to specific campaigns or ad groups. When to use this tool — example user queries: - "what keywords are running in ad group 20031?" - "show me my top performing keywords this month" Routing & params: - channelId: required — use getChannels tool first to retrieve valid values (1-5 channels). Skip any channel with 'hasAdvertisingConnected: false' — it has no advertising connection and this tool will reject it. - fromDate, toDate: required, unix epoch seconds. Server enforces a maximum date range of 6 months. - campaignId, adGroupId: optional — filter to specific campaign/ad group IDs (up to 10 each). Use getAdvertisingCampaigns/getAdvertisingAdGroups first to find IDs. - pageIndex, pageSize, sortKey, sortOrder, currency, status: optional refinements.
getAdvertisingProducts
ChatGPTList advertised product performance across one or more channels. What it does: Returns product-level advertising performance (impressions, clicks, cost, attributed sales, ACOS, ROAS, product_title, image_url, link_url, etc.) for the given channels and date range, optionally scoped to specific product SKUs. The title/image/link fields make this the right tool when the user wants customer-facing product visuals alongside ad metrics. When to use this tool — example user queries: - "show me advertised product performance for SKU B00ABCDEF1" - "which products are getting the most ad spend?" - "show me the top products with their images" Routing & params: - channelId: required — use getChannels tool first to retrieve valid values (1-5 channels). Skip any channel with 'hasAdvertisingConnected: false' — it has no advertising connection and this tool will reject it. - fromDate, toDate: required, unix epoch seconds. Server enforces a maximum date range of 6 months. - productSku: optional — filter to specific product SKUs (up to 10). - pageIndex, pageSize, sortKey, sortOrder, currency, status: optional refinements.
getAdvertisingSearchTerms
ChatGPTList the customer search terms that triggered ads on one channel, with their advertising performance. What it does: Returns one row per search term per ad type (SP or SB; Sponsored Display is not included), summed across every campaign, ad group and keyword that matches the filters. Rows do not say which campaign or keyword produced them, so scope with campaignId, adGroupId or keywordId (pass a single keywordId to see what that keyword triggered). There is no ad type filter; use ad_type. When to use this tool — example user queries: - "which search terms are wasting ad spend this month?" - "what search terms did my keyword 'yoga mat' trigger?" Routing & params: - channelId: required — to find the store the user named, call getChannels with no marketplaces filter and use the channel whose displayName equals that name (ignoring case), with hasAdvertisingConnected: true. A store that only shares a word with the name is a different store. Ad-only accounts are listed with marketplace "advertising", so an amazon filter hides them: if the name is not in a filtered list, call getChannels with marketplaces ["advertising"] before asking the user which store they mean. Never use another store instead. A seller channel and the advertising channel of the same Amazon account return the same rows, so never add the two together. - fromDate, toDate: required — use calculateDateEpoch with timezone "UTC". Rows are stored by the ad account's report date and matched against the UTC dates of fromDate and toDate, so any other timezone can shift the range by a day. Reading the results: - acos, click_through_rate and conversion_rate are percentages (12.5 means 12.5%). roas, cost_per_click and cost_per_acquisition are not. - acos when attributed_sales is 0, and roas when cost is 0, come back as null or 0; neither means perfect efficiency. Other ratios are 0 when their denominator is 0. - Wasted spend (spend with no sales): call with sortKey cost, sortOrder desc and noSalesOnly true, then list the rows in the order returned. noSalesOnly reads pages of 100 terms, so if a page has too few rows, fetch the next pageIndex. - There are no totals. To total a metric over all terms, page through with pageSize 100 until you have read count rows. - Amazon only reports search terms that got at least one click, so impressions are far lower than campaign impressions. - SB has no same-SKU breakdown, so its *_same_sku fields are always 0. - To compare with Search Query Performance (getSqpKeywordTable), call this tool once per searchQuery with searchTerm set to it, and match search_term case-insensitively. One page holds at most 100 terms, so an unfiltered call misses most matches.
getAmazonProductAttributes
ChatGPTRetrieve Amazon catalog attributes for a single ASIN on a seller or vendor channel. What it does: Returns catalog data for the given ASIN — item summary, catalog attributes (brand, bullet points, item name), identifiers (UPC/EAN/etc.), images, sales ranks, classifications, product types, variation/package relationships, and either seller listing data (offers, fulfillment availability, issues, SKU, status) or vendor listing data (vendor details), depending on the channel type. Seller-specific fields are null for vendor channels and vice versa. When to use this tool — example user queries: - "show me the catalog attributes for ASIN B0020MMCJI" - "what's the Amazon listing status for this product?" - "what images and bullet points does Amazon have for this ASIN?" - "show me the product attributes and catalog details for this ASIN" Routing & params: - channelId, merchantId: required — use getChannels tool first to retrieve valid values. Must be an Amazon seller or vendor channel; the request is rejected for non-Amazon channels. - asin: required, exactly 10 letters/numbers (e.g. 'B0020MMCJI').
getChannels
ChatGPTList all connected stores/channels for the account, returning channelId and merchantId for each — the foundational lookup needed before calling most other MerchantSpring tools. Call this first whenever another tool requires channelId or merchantId and you don't already have them. When to use this tool — example user queries: - "list my stores" - "what channels are connected to my account?" - "find my Amazon store" / "look up channel id for Liquid Vault" - "resolve merchant id for a store" - "what marketplaces/channels do I have?" Routing & params: - marketplaces: optional filter (amazon, ebay, shopify, walmart, amazon_vendor, etc.). - countryCodes: optional ISO 3166-1 alpha-3 filter (e.g. USA, GBR, AUS). - Leave both empty to retrieve all channels for the account. - Each channel has a hasAdvertisingConnected flag. Before calling any advertising tool (getAdvertisingCampaigns, getAdvertisingAdGroups, getAdvertisingKeywords, getAdvertisingProducts) with a channelId, skip channels where this is false — they have no advertising connection and those tools will reject them.
getContentChanges
ChatGPTRetrieve content change alerts for an Amazon seller channel: listings whose title, images, bullet points, browse node, product type or relationships changed compared with the stored benchmark. What it does: Returns a paginated list of products (ASIN, title, link, sales rank, last processed) with a per-field status ('same' or 'different'), the live and baseline values, and when each field last changed. How to read the values: 'original' is the listing's live value as last fetched from Amazon. 'benchmark' is the previously accepted baseline, i.e. the "before" value. For a field with status 'different', the change is benchmark -> original (a title that went from A to B has benchmark A, original B). Recency: 'updatedAt' is when the listing was last processed, not when its content changed, so the default sort does not surface recent changes. For "recent changes" questions, set differentKeys and use each field's lastDifferentAt to decide what changed recently. When to use this tool — example user queries: - "which of my listings had content changes recently?" - "show me products where the title or images changed" - "did anyone change the bullet points on B09W9DLNSQ?" - "any listing hijack or content alerts on my Amazon store?" Routing & params: - channelId, merchantId: required — use getChannels first. Amazon seller channels only (marketplace 'amazon'); vendor, filtered and non-Amazon channels are rejected. - differentKeys: optional list of fields to filter on (title, images, bulletPoints, browseNode, productType, relationships). - searchText: optional ASIN or title keyword. - pageIndex (0-based), pageSize (default 100, max 500), sortKey (updatedAt, salesRank or productIdentifier; default updatedAt), sortOrder (default desc).
getCustomGroups
ChatGPTList all custom groups for a merchant store. What it does: Returns all custom product and brand groups configured for a given merchant store (mid). Groups are merchant-scoped — a groupId from one mid cannot be used with another. Use the returned groupIds when calling createGroup, updateGroup, or deleteGroup. When to use this tool — example user queries: - "show me the groups for store X" - "what custom groups do I have?" - "list the product groups on my Amazon store" - "get the group IDs for my merchant" Routing & params: - channelId, merchantId: required — use getChannels tool first to retrieve valid values. - pageIndex, pageSize: optional pagination (defaults fetch the max page size of 100). If a store has more than 100 groups, increase pageIndex to see the rest.
getDirectCostsJobStatus
ChatGPTCheck the status of an updateDirectCosts job. Use this to poll for completion after calling updateDirectCosts. jobStatus is one of IN_PROGRESS, COMPLETED, or FAILED.
getProductProfitAndLoss
ChatGPTFetch P&L for a channel/merchant and date range (epoch seconds). Defaults to profitabilityView 'settled' (cash-basis, driven by settlement timing), which will not tie out against the order-date figures returned by the sales tools over the same window. Pass profitabilityView: 'accrual' whenever comparing or reconciling this P&L against sales figures.
getReportStatus
ChatGPTCheck the status of any generated report. Use this to poll for completion after generating any type of report. Use getChannels tool first to retrieve valid channelId and merchantId values. A status of errored is terminal and can mean either invalid report parameters (e.g. an unsupported reportOptions value such as a bad view) or genuinely no data for the requested window — it is not necessarily a generation failure. If you just introduced or changed a parameter, suspect that parameter (re-check its enumerated values) before concluding the channel has no data.
getSalesByChannels
ChatGPT[IMMEDIATE] Returns sales performance metrics for all channels as JSON instantly — no polling required. Supports time-based comparisons, filtering, pagination, and sorting, and returns direct JSON data without AI summarization. Monetary values, including sales, forecastTarget, budgetTarget, and avOrderValue, are always returned in USD for cross-channel comparison. Report them as USD. This tool does not return the original native-currency amount or exchange rate, so do not attempt an exact native-currency conversion; explain that MerchantSpring dashboards may display the marketplace's native currency instead.
getSalesByPeriod
ChatGPT[IMMEDIATE] Returns JSON time-series data instantly — no polling required. Best for dashboards, trend analysis, and quick queries aggregated by time buckets (daily/weekly/monthly/etc). NOT for product-level breakdown. Retrieve time-series sales performance metrics for a specific channel with configurable time periods and intervals. Returns bucketed data (year/quarter/month/week/day/hour) with current vs prior period comparisons for the specified date ranges. No pagination - returns all time periods within the specified range. Use getChannels tool first to retrieve valid channelId and merchantId values.
getSalesByProduct
ChatGPT[IMMEDIATE] Returns paginated JSON data instantly — no polling required. For product-level sales, prefer this over generateReport with report_type 'salesByProduct', which returns a downloadable file you must poll for. Best for interactive queries, browsing, filtering, and product-level sales lookup with pagination and search. Retrieve paginated sales performance data by product with current and prior period comparisons. Returns direct JSON data including rows and total count. Use getChannels tool first to retrieve valid channelId and merchantId values.
getStoreProfitAndLoss
ChatGPTFetch P&L for a channel/merchant and date range (epoch seconds). Defaults to profitabilityView 'settled' (cash-basis, driven by settlement timing), which will not tie out against the order-date figures returned by the sales tools over the same window. Pass profitabilityView: 'accrual' whenever comparing or reconciling this P&L against sales figures.
getVendorAsins
ChatGPT[IMMEDIATE] Returns one wide row per ASIN instantly — no polling required. Vendor only. Each row combines every data point held for the product: catalogue, ordered revenue, shipped revenue (sourcing and manufacturing), inventory health, purchase orders, product profit, sourcing share and advertising. Supply asin to fetch a single product, or omit it to page through the full master list (products with sales activity in the window). The date range must not exceed 31 calendar days. Page size defaults to 20 and is capped at 50 (rows are wide). Uses zero-based page indexing. Use getChannels tool first to retrieve valid channelId and merchantId values, filtering by marketplace filters amazon_vendor and amazon_vendor_filtered.
getVendorSalesByPeriod
ChatGPTRetrieve time-series vendor sales performance metrics for a vendor specific channel with configurable time periods and intervals. Returns bucketed data (year/quarter/month/week/day/hour) with current vs prior period comparisons including vendor-specific metrics like ordered revenue, shipped revenue, COGS, manufacturing data, and advertising performance. No pagination - returns all time periods within the specified range. This report works ONLY for VENDORS. Use getChannels tool first to retrieve valid channelId and merchantId values, filtering by marketplace filters amazon_vendor and amazon_vendor_filtered
readSummarizedReport
ChatGPTDownload and AI-summarize a completed report to provide insights. Use after generateReport → getReportStatus reports status 'done'. Pass the reportId (plus channelId and merchantId) — the server resolves the report's download location itself, so you never handle the S3 URL.
render-ui
ChatGPTRender one complete final MerchantSpring report from a structured spec. Call this tool exactly once with the final spec. AVAILABLE COMPONENTS (24): - Card: { title?: string, description?: string, className?: string, badge?: string, tooltip?: string } - Branded MerchantSpring card. A titled content container with a header (title + optional subtitle) and a divider, matching the platform's widget cards. Put charts, KPI grids, or tables inside. Omit title for a plain bordered container. badge adds a status pill next to the title; tooltip shows an info icon with a hover tip. [accepts children] - Grid: { columns?: number, gap?: "sm" | "md" | "lg" | "xl", className?: string } - Responsive grid container. columns (1-6) is the max columns on a wide card; it collapses to fewer as the card narrows (container-query responsive). columns: 1 is a full-width row, NOT a narrow cell — required for funnel charts and the report header, and recommended for most charts. columns: 2 is only for intentional side-by-side direct comparisons between max-2 charts such as line, bar, or combo charts. Columns 3-4 are for KPI tiles (MSStatCard) only; 5-6 only for tiny badge/text tiles. Do NOT mix full-width charts and KPI tiles in one Grid — use separate Grids stacked vertically. Column limits: each component's LAYOUT note states its max; the renderer clamps columns to the strictest child limit. [accepts children] - Stack: { direction?: "horizontal" | "vertical", gap?: "none" | "sm" | "md" | "lg" | "xl", align?: "start" | "center" | "end" | "stretch", justify?: "start" | "center" | "end" | "between" | "around", className?: string } - Flex stack. direction vertical (default) stacks children top-to-bottom; horizontal lays them in a row that wraps and collapses to a column as space narrows. gap/align/justify control spacing and alignment. [accepts children] - Separator: { orientation?: "horizontal" | "vertical" } - A thin divider line between sections. orientation horizontal (default) or vertical. - Heading: { text: string, level?: "h1" | "h2" | "h3" | "h4", tone?: "default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | "muted" } - A section heading. level h1-h4 sets size/weight (defaults h2). tone colours the text (info/success/warning/danger/etc.). - Text: { text: string, variant?: "caption" | "body" | "muted" | "lead" | "code", tone?: "default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | "muted" } - A paragraph of text. variant styles it: body (default), caption (small), muted (grey), lead (large intro), or code (monospace). tone colours the text (info/success/warning/danger/etc.); ignored for the code variant. - Badge: { text: string, variant?: "default" | "secondary" | "destructive" | "outline", tone?: "default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | "muted" } - A small status pill. variant default/secondary/destructive/outline. tone gives a branded info/success/warning/danger/etc. pill; overrides variant when set. - Alert: { title: string, message?: string, type?: "success" | "info" | "warning" | "error" } - A compact, single-line status callout — NOT a section title, header, or long-form note. type success/info/warning/error sets the colour. Put the short one-liner in title (required), adding a leading emoji/icon for emphasis as needed; leave message empty or to a brief second clause, never a paragraph. LAYOUT: full-width row recommended; may share a 2-column Grid for direct comparison. - Table: { columns: Array<string | { header: string, align?: "left" | "center" | "right", numeric?: boolean }>, rows: Array<Array<string>>, caption?: string, footerRow?: Array<string>, striped?: boolean } - A simple data table from columns (label strings or {header, align?, numeric?} objects) and rows (string cell arrays). A numeric column right-aligns and uses tabular number spacing. footerRow renders a totals/summary row at the bottom. striped applies zebra-striping to even rows. Optional caption. LAYOUT: full-width ro…
updateGroup
ChatGPTUpdate an existing custom group's name, products, or brands. What it does: Atomically renames a group and/or adds/removes its members. Operations are additive/subtractive — never a full replacement, so unlisted members are unchanged. Product groups and brand groups are mutually exclusive: passing product operations on a brand group (or vice versa) is rejected by the upstream service. Retrieve the groupId from getCustomGroups first. When to use this tool — example user queries: - "add SKU X and Y to my Summer Products group" - "remove SKU Z from the group" - "rename group 'Old Name' to 'New Name'" - "add brand Nike to the Sports Brands group and remove Puma" Routing & params: - channelId, merchantId: required — use getChannels tool first to retrieve valid values. - groupId: required integer — from getCustomGroups. - groupName: optional new name for the group. - addProducts / removeProducts: lists of {sellerSku} for product groups only. - addBrands / removeBrands: lists of brand strings for brand groups only. - At least one field must be provided. Mixing product and brand ops in one call is rejected. - confirm: omit on the first call; re-call with confirm: true to proceed.
calculateDateEpoch
ClaudegenerateReport
ClaudegetAdvertisingByChannels
ClaudegetChannels
ClaudegetProductProfitAndLoss
ClaudegetReportStatus
ClaudegetSalesByChannels
ClaudegetSalesByPeriod
ClaudegetSalesByProduct
ClaudegetStoreProfitAndLoss
ClaudegetVendorSalesByPeriod
ClaudereadSummarizedReport
Clauderender-ui
Claude
