Juicy Profit Analytics

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). 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, net revenue, COGS, ad spend per platform, expenses, income, and net profit, 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.

get_shop_stats

Full detail for one order: line items with costs and profit, refunds, 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, net revenue, COGS, shipping and transaction costs, and gross profit, one row per destination country.

get_country_stats

Per-product sales stats for the authenticated merchant over a date range: sold quantity, gross sales, discounts, returns, COGS and profit before and after returns, with a per-variant breakdown for products that have real variants.

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 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

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 attribution per 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. 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