Juicy Profit Analytics

Update an agency fee entry by id (get the id from get_agency_fees). Overwrites all fields except fixedFee, which is kept when omitted (null removes it). Rates are percentages as decimals (10.5 = 10.5%), from 0 to 100. Past dates are recalculated within seconds. Returns the updated entry.

update_agency_fee

Update a manually-tracked expense by id (get the id from get_expenses). Overwrites title, cost, and date. `cost` is in `currency` (e.g. 12.50), which defaults to the currency stored on the expense. Changing the currency resets the stored conversion rate. Returns the updated expense.

update_expense

Update a manually-tracked income by id (get the id from get_incomes). Overwrites title, amount, and date. `amount` is in `currency` (e.g. 12.50), which defaults to the currency stored on the income. Changing the currency resets the stored conversion rate. Returns the updated income.

update_income

The custom cost of goods (COGS) configuration of one product: a list of cost entries either on the product level or per variant, each with a country whitelist (empty = catch-all), an optional start date, its own currency, and tiered costs (total cost per quantity), plus the fallbackToShopifyCost flag that says whether units no entry applies to use the cost of goods synchronized from Shopify or get none. Returns null when the product has no custom costs. This covers a product sold on its own - the combined cost of a set of products sold together lives in the bundle cost tools (get_bundle_costs).

get_product_costs

Profit & loss report for the authenticated merchant over a date range: gross sales, discounts, returns, taxes, duties, tips, net revenue (total sales - taxes - duties + tips), COGS, ad spend per platform, agency fees (agencyFees, a percentage of ad spend paid to ad agencies), expenses, income, and net profit (after agency fees), grouped into periods.

get_profit_loss

Top product bundles of 2 to 5 products bought together in one order for the authenticated merchant over a date range, ranked by co-occurrence count, with support (share of orders containing the bundle) and lift (co-occurrence vs. chance; >1 means genuine affinity).

get_frequently_bought_together

Revenue, ad spend (per platform), COGS, and profit for the authenticated merchant over a date range. Net profit also subtracts agency fees (agencyFees, a percentage of ad spend paid to ad agencies); ROAS and other ad metrics use platform ad spend only.

get_shop_stats

Full detail for one order: line items with costs and profit, returns, attribution touchpoints, overwrites, and neighboring order ids. Use the order ids returned by get_orders.

get_order_detail

One product of the merchant: the product itself plus its variants with their ids, titles, and the COGS synced from Shopify, the product's custom COGS configuration, and the countries the shop ships to. Variant ids from here are the keys for per-variant entries in update_product_costs.

get_product_detail

Per-country profit stats for the authenticated merchant over a date range: orders, gross sales, discounts, returns, taxes, duties, tips, net revenue (total sales - taxes - duties + tips), COGS, shipping and transaction costs, and gross profit, one row per country (the order's shipping country, or its billing country if it has none). Each row also has an `adSpend` object: the ad spend each platform reports for that country (facebookAdSpend, googleAdSpend, tiktokAdSpend, pinterestAdSpend, snapchatAdSpend, microsoftAdSpend, applovinAdSpend), their sum totalAdSpend, and profitAfterAdSpend (gross profit minus totalAdSpend). profitAfterAdSpend is not net profit: expenses, income and agency fees have no country and are left out, as is ad spend a platform does not report by country. Rows can include countries with ad spend but no orders; a null countryCode is orders or ad spend with an unknown country. Meta reports ad spend for every country an ad reached, so expect many countries with little ad spend and no orders. When presenting the result, summarize countries without orders or sales and under 1% of the total ad spend as "other countries" (name how many and their combined ad spend), as the country page does, instead of listing each one. Keep the null countryCode (unknown country) separate, and only summarize when two or more countries qualify.

get_country_stats

Per-product sales stats for the authenticated merchant over a date range: sold quantity, gross sales, discounts, returns, COGS and profit, profit margin and break-even ROAS before and after returns, with a per-variant breakdown for products that have real variants. Profit only deducts discounts and COGS, not fees or shipping, so the break-even ROAS is usually lower than get_break_even_roas.

get_product_stats

The merchant's third-party logistics (3PL) cost configuration: a list of entries, each with a country whitelist (empty = catch-all), an optional start date, its own currency, tiered pick & pack item costs (total cost per quantity), and fixed/relative per-order costs. Also returns the countries the shop ships to and the default currency.

get_third_party_logistics

The break-even ROAS (return on ad spend) for the authenticated merchant over a date range: the ROAS at which ad spend exactly covers gross profit, i.e. the minimum ROAS the store needs to be profitable.

get_break_even_roas

The shipping lines used on the merchant's orders in the last 90 days (up to 50, most recently used first): the line's code, title, and the order's shipping country. These are exactly the values the shipping cost rules (see get_shipping_costs / update_shipping_costs) are matched against - use them to write rules that hit real shipping lines, or to check which ruleset a line would match.

get_shipping_lines

The merchant's shipping cost configuration: a list of entries, each with an optional start date (null = the initial entry, used before all dated entries) and an ordered list of rulesets. For every order, each of its shipping lines is checked against the date-applicable entry's rulesets top to bottom; the first ruleset whose rules ALL match wins and its cost applies (a ruleset with no rules matches everything). Every costed ruleset prices in its own currency. Call get_shipping_lines to see the real shipping lines this configuration is matched against, and update_shipping_costs to change it.

get_shipping_costs

The merchant's connected ad accounts (platform, accountId, name) that an agency fee's ad account conditions can list. Use these account ids in the conditions of create_agency_fee and update_agency_fee.

get_agency_fee_ad_accounts

The merchant's product catalog: every active product with its id, title, status, creation date, image, and whether cost of goods (COGS) are configured (hasCogs). Use the ids with get_product_detail and the product cost tools.

get_products

The merchant's agency fee entries. An agency fee is a percentage of ad spend and/or a fixed recurring fee paid to an ad agency; it is subtracted from net profit as its own cost line (agencyFees) and is not part of ROAS or other ad platform metrics. Each entry has an optional inclusive date window, a rate (one percentage for all platforms, or one per platform), switches to include ignored Meta campaigns and disconnected ad accounts, optional ad account include/exclude lists per platform, and an optional fixed fee (amount in its own currency, daily, weekly or monthly from the start date, optionally spread over the days of each period). Overlapping entries add up.

get_agency_fees

List the merchant's virtual bundle definitions: which products/variants combine into a bundle, the tiered supplier cost, priority, and attribution mode used to split the cost back onto line items. Bundles price a set of products sold together - a single product's own COGS lives in the product cost tools (get_product_costs).

get_bundle_costs

One page of the merchant's manually-tracked expenses plus their recurring expense schedules, newest first. Pass `page` (1-based) to page through older expenses and `pageSize` to change how many expenses per page (default 100).

get_expenses

One page of the merchant's manually-tracked incomes (revenue outside Shopify orders) plus their recurring income schedules, newest first. Pass `page` (1-based) to page through older incomes and `pageSize` to change how many incomes per page (default 100).

get_incomes

One page of the merchant's orders, newest first, with revenue, costs, profit, and the traffic sources (ad platforms, email, search, referrers) that touched each order. Paginate by passing the last order's processedAt/id as after/afterId (older orders) or the first order's as before/beforeId (newer orders).

get_orders

Replace the custom cost of goods (COGS) configuration of one product. Use this for a single product's own cost - a combined cost for several products sold together belongs in a bundle (create_bundle_cost). Set either product-level entries or per-variant entries, never both; an empty list clears the custom costs. An order picks the entry listing its shipping country, falling back to catch-all entries (empty country list); within the group the most recent started entry wins, the undated entry covers orders before all start dates. Units no entry applies to use the cost of goods synchronized from Shopify when fallbackToShopifyCost is true and get none when it is false. All amounts are decimal values in the entry's currency (e.g. 2.5 = 2.50). Returns the saved configuration.

update_product_costs

Replace the merchant's third-party logistics (3PL) cost configuration with the given entries. An order picks the entry listing its shipping country, falling back to catch-all entries (empty country list); within the group the most recent started entry wins, the undated entry covers orders before all start dates. All amounts are decimal values in the entry's currency (e.g. 2.5 = 2.50). Returns the saved configuration.

update_third_party_logistics

Replace the merchant's whole shipping cost configuration with the given entries (fetch the current one with get_shipping_costs first when only changing part of it). Call get_shipping_lines BEFORE writing rules - rules match on the shipping line's code, title, or the order's country code, and that tool returns the merchant's real shipping lines to match against instead of guessed values. Matching: per order, each shipping line is checked against the date-applicable entry's rulesets top to bottom; the first ruleset whose rules ALL match wins (no rules = matches everything - put such a catch-all last as a default). Cost types: NONE (no cost), FLAT (fixed amount per matched line), QUANTITY (bundle tiers: each bracket is the TOTAL cost for that many units; the largest bundle that fits is charged repeatedly), WEIGHT (tiers by total order weight in grams: the highest reached tier's TOTAL cost applies, tiers are not additive), ACTUAL (use the shipping price the customer paid). FLAT/QUANTITY/WEIGHT carry their own currencyCode; all amounts are decimal values in that currency (e.g. 2.5 = 2.50). Returns the saved configuration.

update_shipping_costs