Store reports and costs

The operations about store reports and costs. Each one is a POST with a JSON object as its body: Making a request has the rules they share.

Which ads earned sales #

POST /api/v1/store.attribution · Read

Spend and the orders it earned, by channel, campaign, ad set or ad (level), for a period: spend, ROAS, the platform's own ROAS, orders, revenue, CPA, NC-ROAS, new customer orders, impressions, clicks and more per row, with the comparison period. Get the siteId from sites.list first. A visit is matched to an ad by the utm_id of its ad click first, then by campaign, ad set and ad names. Rows come sorted by spend, then revenue. Amounts are whole minor units (cents) of one currency, named in labels.currency; spend in another currency is listed in otherCurrencySpend, costs from the cost settings in another currency in otherCurrencyCosts, and neither is added in. Every number names what it covers in its scope: orders_paid (Orders paid in the period, before refunds), credited (Orders credited by the chosen model), credited_estimated (Credited by the chosen model; view credit is an estimate from daily platform totals), platform_reported (As the ad platform reports it), spend_synced (Spend as synced or uploaded, in the account currency), cost_settings (From the cost settings and cost lines of this site), refunds_dated (Refunds dated in the period). Answers 402 workspace_locked while the workspace's dashboards are locked.

Needs a token with the Read permission. Answers 402 while the dashboards of the workspace are locked.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/store.attribution \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

clearsaga store attribution --input '{"siteId":"site_abc123def456"}'

Tool: store_attribution
Arguments: {"siteId":"site_abc123def456"}

Run clearsaga help store attribution for one flag per field.

Store costs #

POST /api/v1/store.costs · Read

The costs the Profit report is computed with: the cost rules (shipping per order, payment fees, a default product cost), the unit cost of each product and the other cost lines. Get the siteId from sites.list first. Every cost is in one currency, named in currency. It still answers while the workspace's dashboards are locked.

Needs a token with the Read permission. Keeps answering while the dashboards of the workspace are locked.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/store.costs \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

clearsaga store costs --input '{"siteId":"site_abc123def456"}'

Tool: store_costs
Arguments: {"siteId":"site_abc123def456"}

Run clearsaga help store costs for one flag per field.

Add a cost line #

POST /api/v1/store.createCostLine · Write

Adds a cost the store carries besides product cost, shipping, fees and ad spend: rent and software per month, a photoshoot once, or returns handling as a share of revenue. Get the siteId from sites.list first. A site holds at most 100 cost lines. Each call adds a line, so sending it twice adds two. Profit changes for every period the line covers.

Needs a token with the Write permission.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/store.createCostLine \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","label":"example","kind":"monthly","amount":0,"startsOn":"2026-10-01","endsOn":"2026-10-01"}'

clearsaga store createCostLine --input '{"siteId":"site_abc123def456","label":"example","kind":"monthly","amount":0,"startsOn":"2026-10-01","endsOn":"2026-10-01"}'

Tool: store_create_cost_line
Arguments: {"siteId":"site_abc123def456","label":"example","kind":"monthly","amount":0,"startsOn":"2026-10-01","endsOn":"2026-10-01"}

Run clearsaga help store createCostLine for one flag per field.

Creative report #

POST /api/v1/store.creatives · Read

Every ad the platforms report for a site, with its thumbnail, format, status, ad set and campaign, and its spend, credited orders and revenue, ROAS, CTR and the platform's own numbers for a period. Get the siteId from sites.list first. Spend uploaded as a CSV has no ads, so it is not here. Amounts are whole minor units (cents) of one currency, named in labels.currency; spend in another currency is listed in otherCurrencySpend, costs from the cost settings in another currency in otherCurrencyCosts, and neither is added in. Every number names what it covers in its scope: orders_paid (Orders paid in the period, before refunds), credited (Orders credited by the chosen model), credited_estimated (Credited by the chosen model; view credit is an estimate from daily platform totals), platform_reported (As the ad platform reports it), spend_synced (Spend as synced or uploaded, in the account currency), cost_settings (From the cost settings and cost lines of this site), refunds_dated (Refunds dated in the period). Answers 402 workspace_locked while the workspace's dashboards are locked.

Needs a token with the Read permission. Answers 402 while the dashboards of the workspace are locked.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/store.creatives \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

clearsaga store creatives --input '{"siteId":"site_abc123def456"}'

Tool: store_creatives
Arguments: {"siteId":"site_abc123def456"}

Run clearsaga help store creatives for one flag per field.

New customers #

POST /api/v1/store.customers · Read

New and returning customers of a period: their orders and revenue, the repeat rate and the days to a second order, weekly or monthly cohorts with how many came back, and lifetime value by the product and by the channel of the first order. Get the siteId from sites.list first. An order is new when it is its customer's first, by the customer key the store sends; without one it is unknown. The model decides the channel of a first order. Amounts are whole minor units of the currency in labels. Answers 402 workspace_locked while the workspace's dashboards are locked.

Needs a token with the Read permission. Answers 402 while the dashboards of the workspace are locked.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/store.customers \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

clearsaga store customers --input '{"siteId":"site_abc123def456"}'

Tool: store_customers
Arguments: {"siteId":"site_abc123def456"}

Run clearsaga help store customers for one flag per field.

Orders and their channels #

POST /api/v1/store.orders · Read

The orders of a period, newest first, each with the channels its journey touched and the one the model credits, and whether the customer was new or returning. Get the siteId from sites.list first. It pages by cursor: the answer holds limit rows (20 unless set, 100 at most) and nextCursor; send that as cursor for the next, older page, until it is null. There is no comparison. Answers 402 workspace_locked while the workspace's dashboards are locked.

Needs a token with the Read permission. Answers 402 while the dashboards of the workspace are locked.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/store.orders \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

clearsaga store orders --input '{"siteId":"site_abc123def456"}'

Tool: store_orders
Arguments: {"siteId":"site_abc123def456"}

Run clearsaga help store orders for one flag per field.

Channel overlap #

POST /api/v1/store.overlap · Read

How the channels of a period share their orders: per channel the orders whose journey touched it, per pair of channels the orders that touched both, and how many orders touched one channel, several, or none. Get the siteId from sites.list first. An order that touched several channels counts fully in each, so the channel rows add up to more than the store's orders. Amounts are whole minor units of the currency in labels. Answers 402 workspace_locked while the workspace's dashboards are locked.

Needs a token with the Read permission. Answers 402 while the dashboards of the workspace are locked.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/store.overlap \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

clearsaga store overlap --input '{"siteId":"site_abc123def456"}'

Tool: store_overlap
Arguments: {"siteId":"site_abc123def456"}

Run clearsaga help store overlap for one flag per field.

Profit report #

POST /api/v1/store.profit · Read

What the store kept in a period: gross sales, then refunds, product cost, shipping, payment fees, ad spend and the other costs, down to contribution and net profit, with margin, MER and the same lines per bucket. Get the siteId from sites.list first. The costs come from the site's cost rules, product costs and cost lines (store.costs); coverage says how many order lines had a product cost, since a missing cost overstates profit. Tax is inside gross, as the store charged it. Amounts are whole minor units (cents) of one currency, named in labels.currency; spend in another currency is listed in otherCurrencySpend, costs from the cost settings in another currency in otherCurrencyCosts, and neither is added in. Answers 402 workspace_locked while the workspace's dashboards are locked.

Needs a token with the Read permission. Answers 402 while the dashboards of the workspace are locked.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/store.profit \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

clearsaga store profit --input '{"siteId":"site_abc123def456"}'

Tool: store_profit
Arguments: {"siteId":"site_abc123def456"}

Run clearsaga help store profit for one flag per field.

Revenue reconciliation #

POST /api/v1/store.reconciliation · Read

Checks, day by day, that the revenue the model credits to every channel (including not attributed) adds up to the revenue the store took. Get the siteId from sites.list first. ok is true when every day matches; days lists each day with the store's revenue, the credited revenue and the difference, in whole minor units of the currency in labels. Answers 402 workspace_locked while the workspace's dashboards are locked.

Needs a token with the Read permission. Answers 402 while the dashboards of the workspace are locked.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/store.reconciliation \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

clearsaga store reconciliation --input '{"siteId":"site_abc123def456"}'

Tool: store_reconciliation
Arguments: {"siteId":"site_abc123def456"}

Run clearsaga help store reconciliation for one flag per field.

Save cost rules #

POST /api/v1/store.saveCostSettings · Write

Changes the cost rules of a site: what shipping one order costs, the payment fee (a share of the order plus a fixed amount) and the product cost of a line whose product has none. Get the siteId from sites.list first. Only the rules sent change. Amounts are minor units of the site's cost currency, which the first cost write pins to the currency of its orders. Profit changes for every past period. Sending the same rules twice changes nothing.

Needs a token with the Write permission.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/store.saveCostSettings \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

clearsaga store saveCostSettings --input '{"siteId":"site_abc123def456"}'

Tool: store_save_cost_settings
Arguments: {"siteId":"site_abc123def456"}

Run clearsaga help store saveCostSettings for one flag per field.

Set product costs #

POST /api/v1/store.setProductCosts · Write

Saves the unit cost of up to 500 products of a site, each by its product id at the store. A product that already has a cost gets the new one. Get the siteId from sites.list first. Costs are minor units of the site's cost currency. A site holds at most 5,000 product costs. Sending the same costs twice changes nothing.

Needs a token with the Write permission.

Input #

Fields of costs

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/store.setProductCosts \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","costs":[{"productId":"ID","unitCostMinor":0}]}'

clearsaga store setProductCosts --input '{"siteId":"site_abc123def456","costs":[{"productId":"ID","unitCostMinor":0}]}'

Tool: store_set_product_costs
Arguments: {"siteId":"site_abc123def456","costs":[{"productId":"ID","unitCostMinor":0}]}

Run clearsaga help store setProductCosts for one flag per field.

Store summary #

POST /api/v1/store.summary · Read

The store's numbers for a period in one answer: revenue, orders, average order, new customers, the returning share, refunds, net profit and margin, ad spend, blended ROAS, MER, CPA and cost per new customer, then the same kind of tiles for each ad platform, each with its change and a sparkline. Get the siteId from sites.list first. Amounts are whole minor units (cents) of one currency, named in labels.currency; spend in another currency is listed in otherCurrencySpend, costs from the cost settings in another currency in otherCurrencyCosts, and neither is added in. Every number names what it covers in its scope: orders_paid (Orders paid in the period, before refunds), credited (Orders credited by the chosen model), credited_estimated (Credited by the chosen model; view credit is an estimate from daily platform totals), platform_reported (As the ad platform reports it), spend_synced (Spend as synced or uploaded, in the account currency), cost_settings (From the cost settings and cost lines of this site), refunds_dated (Refunds dated in the period). reconciliation says whether credited revenue adds up to the store's revenue every day. The store reports take no filter. Answers 402 workspace_locked while the workspace's dashboards are locked.

Needs a token with the Read permission. Answers 402 while the dashboards of the workspace are locked.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/store.summary \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

clearsaga store summary --input '{"siteId":"site_abc123def456"}'

Tool: store_summary
Arguments: {"siteId":"site_abc123def456"}

Run clearsaga help store summary for one flag per field.

Change a cost line #

POST /api/v1/store.updateCostLine · Write

Replaces the label, kind, amount and days of one cost line of a site, by its id from store.costs. Get the siteId from sites.list first. Every field is sent; the answer is the line as saved. An id the site does not have answers 404 with detail cost_line. Profit changes for every period the line covers.

Needs a token with the Write permission.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/store.updateCostLine \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","id":"STORE_ID","label":"example","kind":"monthly","amount":0,"startsOn":"2026-10-01","endsOn":"2026-10-01"}'

clearsaga store updateCostLine --input '{"siteId":"site_abc123def456","id":"STORE_ID","label":"example","kind":"monthly","amount":0,"startsOn":"2026-10-01","endsOn":"2026-10-01"}'

Tool: store_update_cost_line
Arguments: {"siteId":"site_abc123def456","id":"STORE_ID","label":"example","kind":"monthly","amount":0,"startsOn":"2026-10-01","endsOn":"2026-10-01"}

Run clearsaga help store updateCostLine for one flag per field.

Upload product costs #

POST /api/v1/store.uploadProductCosts · Write

Saves product costs from a CSV file: a header row with product_id (or id), an optional product_name, and unit_cost (or cost) in major units such as 26.00. Get the siteId from sites.list first. Rows that cannot be read are skipped and listed with their line number. A currency column, when present, must match the site's cost currency. Uploading the same file twice changes nothing.

Needs a token with the Write permission.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/store.uploadProductCosts \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","csv":"example"}'

clearsaga store uploadProductCosts --input '{"siteId":"site_abc123def456","csv":"example"}'

Tool: store_upload_product_costs
Arguments: {"siteId":"site_abc123def456","csv":"example"}

Run clearsaga help store uploadProductCosts for one flag per field.

Upload ad spend #

POST /api/v1/store.uploadSpend · Write

Saves ad spend from a CSV file, for platforms that are not connected: date, platform (meta, google_ads, tiktok, pinterest or amazon_ads), campaign, optional ad_set and ad, spend in major units, and optional impressions, clicks, conversions, conversion_value and view_conversions. Get the siteId from sites.list first. An upload replaces the uploaded spend of the same platforms over the days the file covers, so uploading a corrected file twice is safe. Rows that cannot be read are skipped and listed.

Needs a token with the Write permission.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/store.uploadSpend \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","csv":"example","currency":"USD"}'

clearsaga store uploadSpend --input '{"siteId":"site_abc123def456","csv":"example","currency":"USD"}'

Tool: store_upload_spend
Arguments: {"siteId":"site_abc123def456","csv":"example","currency":"USD"}

Run clearsaga help store uploadSpend for one flag per field.