Skip to content

API reference Revenue

API reference

Revenue

The API operations about revenue, each with its input, its output and an example.

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

Revenue totals #

POST /api/v1/revenue.kpis · Read

The revenue totals of one site for a period: money taken (gross), money refunded, the difference (net) and the number of orders. Get the siteId from sites.list first; sites.get says in hasRevenue whether the site ever recorded an order. Amounts are whole minor units (cents) of one currency and are never converted or added across currencies. The answer names its currency and lists the others in otherCurrencies; send currency to choose one. Orders count on the day they were paid and refunds on the day they were refunded. Filters change what this answers: with any filter set, it is the revenue credited to the visits that match (label attributed_revenue, attributedOnly true), refunds are not taken off, and orders counts the orders with a matching credited visit. It carries no comparison and no period fields: compare, cfrom and cto are accepted and ignored. For the same totals with a comparison call revenue.report and read summary. 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 #

Field Type Required Description
siteId string required The site id, from sites.list.
range "today" | "yesterday" | "30m" | "12h" | "24h" | "week" | "7d" | "30d" | "60d" | "90d" | "mtd" | "ytd" | "12mo" | "all" | "custom" optional The period to report on: one of today, yesterday, 30m, 12h, 24h, week, 7d, 30d, 60d, 90d, mtd, ytd, 12mo, all. Left out, the workspace's default range is used (30d unless it was changed). For exact dates send from and to and leave range out (custom is accepted with them and means the same). A preset together with dates answers 400.
from string optional First day of a custom period, YYYY-MM-DD in the site's time zone. Send it together with to: one without the other answers 400, and so does a day that does not exist or a from after to. A day after today is read as today; window in the answer shows the period that was used.
to string optional Last day of a custom period, inclusive, YYYY-MM-DD in the site's time zone. Send it together with from.
compare "prev" | "week" | "month" | "quarter" | "year" | "custom" | "off" optional Accepted and ignored: this report has no comparison.
cfrom string optional Accepted and ignored: this report has no comparison.
cto string optional Accepted and ignored: this report has no comparison.
filters object optional Narrow the numbers to matching traffic. An object such as { "country": "us", "path.has": "pricing" }. A plain key means "is"; a key ending in .not means "is not" and a key ending in .has means "contains". Filters are joined with AND. At most 10 keys, of which at most 3 may end in .has. Default: {}. The filter keys are listed under Filters.
currency string optional The currency to report, a three-letter ISO 4217 code in upper case such as USD. Left out, the currency with the most orders in the period is used.

Output #

Field Type Present Description
currency string always The currency of every amount in this answer, an ISO 4217 code such as USD. Amounts are whole minor units (cents).
multiCurrency boolean always True when the period also holds orders in other currencies. They are listed in otherCurrencies and never added in.
otherCurrencies array of object always The other currencies of the period: code, the number of orders and their gross amount in minor units of that currency. Pass a code as currency to get its numbers.
grossMinor number always Money taken in the period, before refunds. With a filter: the part credited to the matching visits.
refundsMinor number always Money refunded in the period, counted by the day of the refund. 0 with a filter, where refunds are not applied.
refundCount number always The number of refunds in the period.
netMinor number always grossMinor minus refundsMinor.
orders number always The number of orders paid in the period. With a filter: the orders with a credited visit that matches.
attributedOnly boolean always True when a filter was set, so the amounts are revenue credited to matching visits and not the whole takings.
label "revenue" | "net_revenue" | "attributed_revenue" always What the dashboard calls the main number: revenue (no refunds in the period), net_revenue (refunds were taken off) or attributed_revenue (a filter was set).
hasOrdersEver boolean always False when the site never recorded an order, in which case every number is 0.

Example #

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

Run clearsaga help revenue kpis for one flag per field.

Refunds list #

POST /api/v1/revenue.refunds · Read

The refunds of one site in a period and one currency, newest first: when each happened, the product, the order number at the payment provider and the amount. Get the siteId from sites.list first. currency is required here; revenue.kpis names the currencies of the period. Amounts are whole minor units (cents). 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. A cursor this list did not issue answers an empty last page. There is no total. Only the period and the currency are used: filters and the comparison are accepted and ignored, and the answer carries no period fields. 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 #

Field Type Required Description
siteId string required The site id, from sites.list.
range "today" | "yesterday" | "30m" | "12h" | "24h" | "week" | "7d" | "30d" | "60d" | "90d" | "mtd" | "ytd" | "12mo" | "all" | "custom" optional The period to report on: one of today, yesterday, 30m, 12h, 24h, week, 7d, 30d, 60d, 90d, mtd, ytd, 12mo, all. Left out, the workspace's default range is used (30d unless it was changed). For exact dates send from and to and leave range out (custom is accepted with them and means the same). A preset together with dates answers 400.
from string optional First day of a custom period, YYYY-MM-DD in the site's time zone. Send it together with to: one without the other answers 400, and so does a day that does not exist or a from after to. A day after today is read as today; window in the answer shows the period that was used.
to string optional Last day of a custom period, inclusive, YYYY-MM-DD in the site's time zone. Send it together with from.
compare "prev" | "week" | "month" | "quarter" | "year" | "custom" | "off" optional Accepted and ignored: this list has no comparison.
cfrom string optional Accepted and ignored: this list has no comparison.
cto string optional Accepted and ignored: this list has no comparison.
filters object optional Accepted and ignored: this report applies no filter. Default: {}. The filter keys are listed under Filters.
currency string required The currency of the refunds to list, a three-letter ISO 4217 code in upper case such as USD. Required.
cursor string, at most 200 characters optional Where to continue: the nextCursor of the page before. Leave it out for the newest refunds.
limit integer, 1 to 100 optional Rows per page, 1 to 100. 20 when left out.

Output #

Field Type Present Description
rows array of object always The refunds of the period in the chosen currency, newest first: occurredAt is the time of the refund in milliseconds since 1970 UTC, productName the product of the refunded order when it is known, providerOrderId the order number at the payment provider, and amountMinor the refunded amount in minor units (cents) of currency.
nextCursor string | null always Send this as cursor to get the next, older page. Null on the last page.

Example #

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

Run clearsaga help revenue refunds for one flag per field.

Revenue attribution report #

POST /api/v1/revenue.report · Read

Where the revenue of one site came from in a period: the totals with the comparison period, how many orders could be tied to a visit, and credited revenue by landing page, by the page before the order, by the source of the first and of the last visit, by product, by the number of visits before buying and by page sequence. Get the siteId from sites.list first. An order is tied to a visit through an id the website passes to its payment provider; orders without one are counted in coverage as no_id. Amounts are whole minor units (cents) of one currency and are never converted or added across currencies. Send currency to choose one; currencies lists those with orders in the period. group chooses whether sources are referring sites or channels. Credit follows the site's attribution settings, which are in settings (lookback days and model). This report ignores every filter: the filters that were sent change nothing and are listed in ignoredFilters, each once by its plain key (path for path.has). Nothing pages. 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 #

Field Type Required Description
siteId string required The site id, from sites.list.
range "today" | "yesterday" | "30m" | "12h" | "24h" | "week" | "7d" | "30d" | "60d" | "90d" | "mtd" | "ytd" | "12mo" | "all" | "custom" optional The period to report on: one of today, yesterday, 30m, 12h, 24h, week, 7d, 30d, 60d, 90d, mtd, ytd, 12mo, all. Left out, the workspace's default range is used (30d unless it was changed). For exact dates send from and to and leave range out (custom is accepted with them and means the same). A preset together with dates answers 400.
from string optional First day of a custom period, YYYY-MM-DD in the site's time zone. Send it together with to: one without the other answers 400, and so does a day that does not exist or a from after to. A day after today is read as today; window in the answer shows the period that was used.
to string optional Last day of a custom period, inclusive, YYYY-MM-DD in the site's time zone. Send it together with from.
compare "prev" | "week" | "month" | "quarter" | "year" | "custom" | "off" optional What the period is compared with: prev (the period just before, the default), week, month, quarter or year earlier, custom (cfrom and cto are then required), or off for no comparison. The range all never has a comparison.
cfrom string optional First day of a custom comparison period, YYYY-MM-DD. Required with compare set to custom, where a day that does not exist or a cfrom after cto answers 400.
cto string optional Last day of a custom comparison period, inclusive, YYYY-MM-DD. Required with compare set to custom.
filters object optional Accepted and ignored: this report applies no filter. The filters that were sent come back in ignoredFilters, each named once by its plain key. Default: {}. The filter keys are listed under Filters.
currency string optional The currency to report, a three-letter ISO 4217 code in upper case such as USD. Left out, the currency with the most orders in the period is used.
group "referrer" | "channel" optional How firstSource and lastSource are grouped: referrer (by referring site, the default) or channel.

Output #

Field Type Present Description
serverNow number always The clock the period was resolved with: the start of the next whole minute, milliseconds since 1970 UTC.
serverTime number always When the answer was built, milliseconds since 1970 UTC.
window object always The period the numbers cover: from and to in milliseconds since 1970 UTC (to is exclusive), the time zone, a label and the bucket size.
compare object | null always The comparison period (from, to, tz, label, granularity, token) with the same totals for it as summary has. Null when there is no comparison.
rawFrom number | null always The earliest time detailed data is kept from, or null when nothing was trimmed.
truncated boolean always True when a filtered answer could only cover the part of the period that still has detailed data.
currency string always The currency of every amount in this answer, an ISO 4217 code. Amounts are whole minor units (cents).
currencies array of object always Every currency with orders in the period: code, the number of orders and their gross amount in minor units of that currency. Pass a code as currency to get its report.
summary object always The totals of the period. grossMinor is the money taken, refundsMinor the money refunded (refundCount refunds) and netMinor the difference; orders is the number of orders. attributedMinor and attributedOrders are the part that could be tied to a recorded visit, attributionRate is attributedOrders divided by orders (a fraction from 0 to 1, null without orders), and medianTimeToBuyMs is the median time from a buyer's first visit to the order in milliseconds (null when no order could be tied to a visit).
coverage array of object always How many orders could be tied to a visit. attributed: tied to a recorded visit. id_no_visit: the order carried a visitor id but no visit was found in the lookback window. no_id: the order carried no id. share is the part of all orders, a fraction from 0 to 1.
breakdown object always Credited revenue split four ways, each a list of { key, label, orders, revenueMinor }: by the first page of the buyer's journey (landingPages), by the page viewed last before the order (convertingPages), and by the source of the first and of the last visit (firstSource, lastSource). Sources are referring sites, or channels when group is channel.
products array of object always Revenue per product: its name, whether it is a subscription or a one-time purchase, orders, revenueMinor, share of the period's revenue and attributedShare, the part of its revenue tied to a visit. Shares are fractions from 0 to 1.
touches array of object always Orders grouped by how many visits the buyer made before buying: 1, 2-3, 4-6, 7-10 or 11+.
paths array of object always The page sequences that most often led to an order: the pages in order, truncated true when the sequence was cut short, and the orders and revenue behind it.
settings object always The attribution settings the report was computed with: how many days back a visit can earn credit, and the model (last_touch, first_touch or linear).
ignoredFilters array of string always The filters of the input. This report applies no filter, so every filter that was sent is listed here. A filter is named once by its plain key, whichever form was sent: path.has and path.not are both listed as path.

Example #

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

Run clearsaga help revenue report for one flag per field.

Revenue over time #

POST /api/v1/revenue.timeseries · Read

Money taken, orders and money refunded per bucket of a period, for one site and one currency. Get the siteId from sites.list first. Amounts are whole minor units (cents) of one currency and are never converted or added across currencies. Send currency to choose one. The bucket size follows the period and is named in window.granularity. Orders count in the bucket they were paid in and refunds in the bucket they were refunded in. This report ignores every filter: the filters object is accepted and changes nothing. It has no comparison series either. 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 #

Field Type Required Description
siteId string required The site id, from sites.list.
range "today" | "yesterday" | "30m" | "12h" | "24h" | "week" | "7d" | "30d" | "60d" | "90d" | "mtd" | "ytd" | "12mo" | "all" | "custom" optional The period to report on: one of today, yesterday, 30m, 12h, 24h, week, 7d, 30d, 60d, 90d, mtd, ytd, 12mo, all. Left out, the workspace's default range is used (30d unless it was changed). For exact dates send from and to and leave range out (custom is accepted with them and means the same). A preset together with dates answers 400.
from string optional First day of a custom period, YYYY-MM-DD in the site's time zone. Send it together with to: one without the other answers 400, and so does a day that does not exist or a from after to. A day after today is read as today; window in the answer shows the period that was used.
to string optional Last day of a custom period, inclusive, YYYY-MM-DD in the site's time zone. Send it together with from.
compare "prev" | "week" | "month" | "quarter" | "year" | "custom" | "off" optional What the period is compared with: prev (the period just before, the default), week, month, quarter or year earlier, custom (cfrom and cto are then required), or off for no comparison. The range all never has a comparison.
cfrom string optional First day of a custom comparison period, YYYY-MM-DD. Required with compare set to custom, where a day that does not exist or a cfrom after cto answers 400.
cto string optional Last day of a custom comparison period, inclusive, YYYY-MM-DD. Required with compare set to custom.
filters object optional Accepted and ignored: this report applies no filter. Default: {}. The filter keys are listed under Filters.
currency string optional The currency to report, a three-letter ISO 4217 code in upper case such as USD. Left out, the currency with the most orders in the period is used.

Output #

Field Type Present Description
serverNow number always The clock the period was resolved with: the start of the next whole minute, milliseconds since 1970 UTC.
serverTime number always When the answer was built, milliseconds since 1970 UTC.
window object always The period the numbers cover: from and to in milliseconds since 1970 UTC (to is exclusive), the time zone, a label and the bucket size.
compare object | null always The comparison period in the same form, or null when there is none.
rawFrom number | null always The earliest time detailed data is kept from, or null when nothing was trimmed.
truncated boolean always True when a filtered answer could only cover the part of the period that still has detailed data.
currency string always The currency of the amounts, an ISO 4217 code. Amounts are whole minor units (cents).
points array of object always One point per bucket of the period, oldest first: start and end in milliseconds since 1970 UTC (end exclusive), partial true while the bucket is still running, the money taken (grossMinor), the number of orders and the money refunded (refundsMinor) in it.

Example #

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

Run clearsaga help revenue timeseries for one flag per field.