create_agency_fee
ChatGPTCreate an agency fee entry: a percentage of ad spend and/or a fixed recurring fee paid to an ad agency, subtracted from net profit (not part of ROAS). Rates are percentages as decimals (10.5 = 10.5%), from 0 to 100; for a fixed fee only, use an AllPlatforms rate of 0. A fixed fee needs a start date. Past dates in the window are recalculated within seconds. Returns the created entry.
create_bundle_cost
ChatGPTCreate a virtual bundle: a set of products/variants that, together, carry one combined tiered supplier cost instead of pricing at their individual single-item costs. Use this only when the cost applies to the combination - a single product's own COGS is set with update_product_costs. Each cost entry's sourceCurrency is the currency its tier totals are in. Returns the created bundle, including its new id.
create_expense
ChatGPTCreate a manually-tracked expense for the merchant. cost is in currency (e.g. 12.50), which defaults to the store's display currency. Set spreadFromDate to spread the cost evenly across each day from that date up to date. Returns the ids of the created expenses.
create_income
ChatGPTCreate a manually-tracked income (revenue outside Shopify orders) for the merchant. amount is in currency (e.g. 12.50), which defaults to the store's display currency. Set spreadFromDate to spread the amount evenly across each day from that date up to date. Returns the ids of the created incomes.
delete_agency_fee
ChatGPTDelete an agency fee entry by id (get the id from get_agency_fees). Its fees are removed from net profit for all dates.
delete_bundle_cost
ChatGPTDelete a virtual bundle by id (get the id from get_bundle_costs).
delete_expense
ChatGPTDelete a manually-tracked expense by id (get the id from get_expenses).
delete_income
ChatGPTDelete a manually-tracked income by id (get the id from get_incomes).
delete_product_costs
ChatGPTDelete the custom cost of goods (COGS) configuration of one product. Afterwards the product falls back to the COGS synchronized from Shopify, if any.
get_agency_fee_ad_accounts
ChatGPTThe 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_fees
ChatGPTThe 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_break_even_roas
ChatGPTThe 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_bundle_costs
ChatGPTList 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_country_stats
ChatGPTPer-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_expenses
ChatGPTOne 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_frequently_bought_together
ChatGPTTop 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_incomes
ChatGPTOne 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_order_detail
ChatGPTFull 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_orders
ChatGPTOne 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_product_costs
ChatGPTThe 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_detail
ChatGPTOne 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_stats
ChatGPTPer-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_products
ChatGPTThe 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_profit_loss
ChatGPTProfit & 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_return_costs
ChatGPTThe merchant's return cost configuration: a list of entries, each with a country whitelist (empty = catch-all), an optional start date, its own currency, the kinds of returns it charges (restocked returns, non-restocked returns, restocked refunds without a return), when it counts a return (openReturns: WHEN_PROCESSED = once closed or its goods are restocked / not restocked, WHEN_REFUNDED = also at its first refund, ALWAYS = also when created), a flat fee per return, and fees per returned unit / distinct product / line item and per restocked unit / distinct product / line item. Also returns the countries the shop ships to and the default currency.
get_shipping_costs
ChatGPTThe 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_lines
ChatGPTThe 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_shop_stats
ChatGPTRevenue, 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_third_party_logistics
ChatGPTThe 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.
update_agency_fee
ChatGPTUpdate 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_bundle_cost
ChatGPTUpdate an existing virtual bundle by id (get the id from get_bundle_costs). Overwrites every field. Each cost entry's sourceCurrency is the currency its tier totals are in. Returns the updated bundle.
update_expense
ChatGPTUpdate 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_income
ChatGPTUpdate 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_product_costs
ChatGPTReplace 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_return_costs
ChatGPTReplace the merchant's return cost configuration with the given entries. A return only considers entries whose scopes include its kind; among those it picks the entry listing the order's shipping country, falling back to catch-all entries (empty country list); within the group the most recent started entry wins, the undated entry covers returns before all start dates. A return is booked on the first of its creation, first refund and processing date whose entry on that date counts it per its openReturns. Declined and canceled returns never count. No entry left = no cost. Every entry needs at least one scope. All amounts are decimal values in the entry's currency (e.g. 2.5 = 2.50); negative amounts are rejected. Returns the saved configuration.
update_shipping_costs
ChatGPTReplace 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_third_party_logistics
ChatGPTReplace 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.