Bloom Profit Analytics

Marketing Efficiency for the authenticated Bloom shop — the same model as the Marketing Efficiency page: is ad spend profitable, is the next dollar profitable, do new customers pay back, and what budget is recommended. WINDOWS ARE FIXED by the model (no date range input): weekly series covers the trailing ~3 months in 7-day buckets ending yesterday; cohorts are the trailing 6 calendar months of new customers with a 60-day LTV horizon. Use `as_of` to evaluate the model as it stood on a past date. SECTIONS (pick via `sections`, default weekly, scale, advice): - weekly: per 7-day bucket — adSpend, netRevenue, ncRevenue, blendedROAS, poas, beroas (break-even ROAS), newCustomers, ncCAC, ncAOV, ncROAS, ncPOAS, firstOrderProfit, profitLTV60, repeatRate60, paybackDays. - cohorts: monthly new-customer cohorts — new_customers, aov, cac, fop (first-order profit), profit_ltv_60, ltv_to_cac, payback_days, repeat_rate, maturity_pct, is_estimated. (60-point curve_points omitted.) - mature: the most recent fully matured cohort's CAC / LTV / payback. - payback_curve: cumulative profit per customer by day vs CAC. - marginal: spend-response curve, marginal ROAS at current spend, ceiling budget, reliability. - scale: headline gauges — blended_roas, beroas, nc_beroas, current_daily_budget, marginal_at_current, ceiling_budget, payback_gauge. - advice: verdict state + cause, recommended/trim/next daily budget, next_review, and the 5 gate checks (ads_profitable, next_dollar, customers_pay_back, repeat_pace, first_order_covers_cac). RESPONSE: { as_of, currency, window, sections requested… }. Money in reporting currency; percentages already × 100. MULTISTORE: single shop only. Pass `shop_id` to target one shop; call `list_shops` first to discover IDs.

query_marketing_efficiency

Query per-order metrics for the authenticated Bloom shop. Mirrors the merchant's Order Metrics table. USAGE: 1. For wide date ranges (>1 month) call FIRST with `count_only: true` to gauge size. Response includes `count` and `suggest_batches`. 2. If `count` is large (>500), narrow `start_date`/`end_date` OR paginate using `offset` (start at 0, increment by `limit` each call until `has_more` is false). 3. Pick only the fields you need via `fields` — fewer columns = smaller payload + faster query. AVAILABLE FIELDS: order_name, shopify_order_id, created_at, source_name, tags, gross_sales, discounts, refunds, net_sales, tax, total_sales, shopify_gross_profit, shopify_gross_margin_pct, cm1, cm1_pct, cm2, cm2_pct, gateway_cost, shipping_cost, product_cost, handling_cost, channel_fee, tariff_cost, disputes. cm1 = Product Gross Profit (total_sales - product_cost). cm2 = Gross Profit (cm1 minus handling/shipping/payment/channel/tariff costs). Row key for cm2 is "Gross Profit". RESPONSE: { count, rows, offset, limit, next_offset, has_more }. All currency values are in shop's reporting currency. Percentages are already multiplied by 100. MULTISTORE: if the user has multiple connected shops, pass `shop_id` to target one. Call `list_shops` first to discover available shops and match the user's phrasing. Returned amounts are in that shop's `reporting_currency` (see `list_shops`). When comparing or summing across shops with different reporting_currencies, label each value with its currency rather than silently summing — confirm with the user before applying any FX conversion.

query_order_profits

Product Insights for the authenticated Bloom shop: every product classified into an action bucket for a date range. Same engine as the Product Insights page (Performance / Ads / Momentum tabs). TABS (pick one via `tab`): - performance: units, gross/net revenue, discounts, refunds, COGS, shipping, gross profit + margin, refund/discount rate, shop 90d benchmarks. Category ∈ Profit Star / Revenue Trap / Margin Bleeder / Hidden Gem / Underperformer / Dead Weight / Cost Missing with a recommended Action. - ads: per-product ad spend, ad revenue, actual vs break-even ROAS, contribution margin, net profit after ads. Category ∈ Profit Maker / Margin Trap / Budget Drain / Money Pit / Hidden Gem / Dead Weight. Tune with `target_roas` (default 2.0) and `margin_floor` % (default 30). - momentum: FIXED window only — last `lookback` days ending today (7/14/30/60/90, default 30) vs the same-length window immediately before it, exactly like the Momentum tab. start_date/end_date are IGNORED for this tab. Units, revenue, profit for both windows plus % change and Label ∈ On Fire / In Freefall / Margin Squeeze / Profit Engine / Losing Steam / Holding Steady / New / Low Volume. `New` and `Low Volume` rows are Excluded=true. Tune with `momentum_threshold` % (default 5) and `min_units` prior-window floor (default 5). PRODUCT COUNTS DIFFER BY TAB — this is by design, not a data inconsistency: performance lists every product incl. unsold; ads lists products with a daily product summary row in range (ad spend may be 0); momentum lists products with units sold in the current or prior window. Do not compare row counts across tabs. USAGE: pass a tab (+ start_date/end_date for performance/ads, `lookback` for momentum), optionally `category` to filter to one bucket, and paginate with limit/offset. Performance/Ads are sorted by gross profit / ad spend DESC; Momentum by current revenue DESC. RESPONSE: { tab, currency, count, rows, offset, limit, next_offset, has_more }. Row keys are human column names (e.g. "Product Name", "Product Gross Profit"). Percentages already × 100. CURRENCY: `ads` values are in reporting currency; `performance` and `momentum` are in the shop's NATIVE currency. Performance and Ads read different fact tables, so COGS/profit for the same product can differ slightly between tabs. MULTISTORE: single shop only. Pass `shop_id` to target one shop; call `list_shops` first to discover IDs.

query_product_insights

Query per-product (or per-variant) metrics for the authenticated Bloom shop. Mirrors the merchant's Product Metrics table. GRAIN: `grain: "product"` (default) for one row per product, `grain: "variant"` for per-variant. variant_name and sku apply only to variant grain; every other field works in both grains. USAGE: 1. For wide date ranges (>1 month) call FIRST with `count_only: true` to gauge size. 2. If `count` is large (>500), narrow the date range OR paginate using `offset`. 3. Pick only the fields you need via `fields`. AVAILABLE FIELDS: product_name, product_id, variant_name, image, product_type, vendor, sku, tags, status, units_sold, units_refunded, inventory_quantity, gross_sales, discounts, refunds, net_sales, total_sales, product_cogs, gross_profit, gross_margin_pct, ads_spend, net_profit, net_profit_margin, product_roas, inventory_cost, inventory_value, shipping_cost, beroas. ads_spend = blended across Meta/Google/etc. net_profit = total_sales - cogs - ads_spend - handling. product_roas = total_sales / ads_spend. beroas = break-even ROAS. RESPONSE: { grain, count, rows, offset, limit, next_offset, has_more }. All currency in shop's reporting currency. Percentages already × 100. MULTISTORE: if the user has multiple connected shops, pass `shop_id` to target one. Call `list_shops` first to discover available shops and match the user's phrasing. Returned amounts are in that shop's `reporting_currency` (see `list_shops`). When comparing or summing across shops with different reporting_currencies, label each value with its currency rather than silently summing — confirm with the user before applying any FX conversion.

query_product_profits

Full Profit & Loss statement for the authenticated Bloom shop — the same rows as the P&L page. Use `source` to pick Shopify, Amazon, or the combined Overall P&L. - shopify: revenue → refunds/discounts → COGS → fulfillment (shipping, handling, transaction fees) → marketing spend by channel → contribution margins → operating expenses → net profit. - amazon: Gross Revenue → Returns & Refunds → Net Revenue → COGS → Product Gross Profit → Amazon Fees (Referral/Commission, Order Fulfillment) → Gross Profit → Marketing Spend (Sponsored Products/Brands/Display, DSP, deals, coupons) → Contribution Profit → Operating Expenses (supply chain & storage, reimbursements, other Amazon fees) → Net Profit. Amazon costs are NEGATIVE numbers; fees for unsettled orders are estimated until Amazon settles them. Requires Amazon connected. - all: both channels combined. USAGE: one row per period (`group_by` auto: ≤7d=day, ≤31d=week, ≤366d=month, else year) plus a row with Date="Total" for the whole range. Default `fields` = the headline P&L lines; pass `fields: ["all"]` for every line item, or an explicit list of row names. Call with a short range first to see available row names. RESPONSE: { source, currency, group_by, count, rows }. Values in reporting currency; margin rows already × 100. MULTISTORE: single shop only. Pass `shop_id` to target one shop; call `list_shops` first to discover IDs.

query_profit_loss

Headline KPI scorecards for the authenticated Bloom shop over a date range — the KPI tiles at the top of the Marketing and Customers dashboards. DOMAINS: marketing (ROAS (API), Conversion Value, Conversions, Ad Spend, Clicks — across connected ad platforms); customers (New Customer %, Repeat Customer %, New/Repeat Customer Revenue, AOV, AOV new vs returning). `compare: true` also returns the same-length period immediately before with change_pct. RESPONSE: { domain, currency, period, previous_period, widgets: [{ name, value, previous_value, change_pct, is_currency, is_percentage }] }. Values in reporting currency; percentages already × 100. MULTISTORE: single shop only. Pass `shop_id` to target one shop; call `list_shops` first to discover IDs.

query_scorecards

Settings that change how every other tool's numbers should be read, for the authenticated Bloom shop: currency (native vs reporting), timezone, profit_calc_mode (net_revenue vs total_revenue as the margin base), tax handling, shipping-revenue treatment, the merchant's default dashboard date range, plan, store age, and which integrations are connected. Cheap — call once per conversation. MULTISTORE: pass `shop_id` to target one shop; call `list_shops` first to discover IDs.

query_shop_settings

Data freshness for the authenticated Bloom shop: which integrations are connected and when each data source (Shopify orders, ad platforms, email, shipping, Amazon) last finished syncing. Call this before answering questions about very recent days, or when numbers look incomplete — a source with status ERROR or an old synced_till explains gaps. RESPONSE: { shop_id, timezone, first_time_synced, overall, connected_integrations, sources: [{ resource, status, synced_till, updated_at }] }. overall ∈ ok / not_integrated (no ad platform connected) / not_synced (connected but no data yet). status ∈ PENDING / RUNNING / COMPLETED / ERROR. MULTISTORE: pass `shop_id` to target one shop; call `list_shops` first to discover IDs.

query_sync_status

Set the fulfillment handling cost Bloom charges per order and per item (Costs → Handling Cost), in the shop's NATIVE currency. `country` defaults to Worldwide, the rate used for every shipping country without its own override; pass a country name to set an override for that country only. One row per country; calling again updates it. No date range: applies to new orders, and to past orders too when `recalculate_past_orders` is true (default true); pass false to apply to new orders only. Preview shows the current per-order / per-item cost for that country and the new one. CONFIRMATION (required): call once WITHOUT `confirm` to get a preview of exactly what will change and a short `confirmation_code`. Show the preview to the merchant and ask them to approve it. Only after they explicitly say yes, call again with `confirm: true` and the code. Never confirm on the merchant's behalf. After applying, tell them where in the Bloom app to verify (`verify_in_app`). This tool only creates or updates — it never deletes. MULTISTORE: on accounts with more than one shop you must also pass `shopify_domain` matching the target store; call `list_shops` to see domains.

set_handling_cost

Set the payment processing fee Bloom charges against orders for a gateway (Costs → Gateway Cost): `percentage_fee` % of order value plus `fixed_fee` per order, in the shop's NATIVE currency (e.g. 2.9 + 0.30). One rate per gateway and country per shop; calling again updates it. `gateway_name` must be one of Bloom's known gateways — `Other` is the catch-all applied to any gateway without its own rate. `country` defaults to Worldwide, the rate used for every order country without its own override; pass a country name to set an override for that country only. A fee Shopify reports itself (Shopify Payments, PayPal) always wins over these rates. Fees have no date range: they apply to new orders, and to past orders too when `recalculate_past_orders` is true (default true); pass false to apply to new orders only. Preview shows the current rate for that gateway (if any) and the new one. CONFIRMATION (required): call once WITHOUT `confirm` to get a preview of exactly what will change and a short `confirmation_code`. Show the preview to the merchant and ask them to approve it. Only after they explicitly say yes, call again with `confirm: true` and the code. Never confirm on the merchant's behalf. After applying, tell them where in the Bloom app to verify (`verify_in_app`). This tool only creates or updates — it never deletes. MULTISTORE: on accounts with more than one shop you must also pass `shopify_domain` matching the target store; call `list_shops` to see domains.

set_gateway_cost

Set the cost of goods (COGS) for product variants — the same effect as the bulk cost import on Costs → Product Cost. Use it to fix "Cost Missing" products from query_product_insights or to correct wrong COGS. Each item names a variant by `variant_id` (Shopify variant id) or `sku`, plus the new `cost` per unit in the shop's NATIVE currency (> 0). A SKU that matches several variants is rejected with the candidates so you can pass variant_id instead. Only variants of ACTIVE products can be updated; draft and archived products are rejected. Shopify products only — Amazon catalogue costs cannot be set with this tool. The new cost replaces ALL existing Bloom cost rules for that variant (all countries, date ranges and quantity tiers) with one fixed worldwide cost from store creation onward. `recalculate_past_orders` (default true) re-runs profit for historical orders; false applies to new orders only. Changes reach reports within about a minute. PREVIEW returns, per variant: product/variant title, sku, current Shopify cost, current Bloom cost rules, new cost. CONFIRMATION (required): call once WITHOUT `confirm` to get a preview of exactly what will change and a short `confirmation_code`. Show the preview to the merchant and ask them to approve it. Only after they explicitly say yes, call again with `confirm: true` and the code. Never confirm on the merchant's behalf. After applying, tell them where in the Bloom app to verify (`verify_in_app`). This tool only creates or updates — it never deletes. MULTISTORE: on accounts with more than one shop you must also pass `shopify_domain` matching the target store; call `list_shops` to see domains.

set_product_cost

Set the commission Bloom deducts for orders from a sales channel or order source (Costs → Channel Commission): `commission_fee` is a percentage of the order total (e.g. 15 for a 15% marketplace fee). `channel_name` must be one of the channels seen on this shop's orders (e.g. Online Store, Amazon, TikTok, Faire, POS); unknown names are rejected with the available list. One rate per channel; calling again updates it. No date range: applies to new orders, and to past orders too when `recalculate_past_orders` is true (default false). Preview shows the current commission for that channel (if any) and the new one. CONFIRMATION (required): call once WITHOUT `confirm` to get a preview of exactly what will change and a short `confirmation_code`. Show the preview to the merchant and ask them to approve it. Only after they explicitly say yes, call again with `confirm: true` and the code. Never confirm on the merchant's behalf. After applying, tell them where in the Bloom app to verify (`verify_in_app`). This tool only creates or updates — it never deletes. MULTISTORE: on accounts with more than one shop you must also pass `shopify_domain` matching the target store; call `list_shops` to see domains.

set_channel_commission