Listing stats

​

Where the numbers come from

Every number on this page comes from your shop’s orders, as Alura synced them from Etsy. After each sync, Alura adds up each listing’s sales per day. The API reads those daily totals and never calls Etsy.

• Day. A sale counts on the UTC date the order was placed. A refund counts on the UTC date of the refund, not the order’s. A review counts on the UTC date it was written.
• Order states. Canceled orders don’t count, and neither do their refunds.
• Refunds stay separate. revenue isn’t reduced by refunds. When Etsy records a refund for a whole order, Alura splits it across the order’s items by their revenue.
• Not in revenue: shipping, sales tax, VAT, gift wrap and Etsy’s fees. revenue is what the items sold for.
• No profit or margin per listing. They aren’t reliable at listing level. For profit, see Shop stats.

Every measure is null, never 0, for a day Alura doesn’t know. A covered day with no sales is a real 0. See Coverage.

​

Listing stats

Listing stats return a listing’s totals over a range, a series of points, and a few lifetime figures.

• Range. from and to are UTC days, both included. By default they span the shop’s whole coverage window. include: ["stats"] on get_my_listing always uses that default.
• Interval. interval is day, week, month (the default), quarter or year, with at most 366 points. Over MCP, get_my_listing with include: ["stats"] takes no interval: it returns at most 24 points, by month, or by quarter and then by year when the history is longer than 24 months (interval says which). Weeks start on Monday. The first and last points are cut to the range.
• Totals add up the known days of the range.
• lifetime holds views and favorites, Etsy’s lifetime counters for the listing. Etsy keeps no history of them.
• metrics.age_days is the number of whole UTC days since the listing was first created.
• metrics.review_rate is reviews per unit sold over the covered days of the range, to 4 decimals. It’s null when units are 0 or unknown, when the range has a gap day, or when the range runs past the last day Alura synced reviews for.
• metrics.rating is the average rating, to 2 decimals, and the share of each star rating, over every stored review of the listing, not only those in the range.

Null points. A point is null for its sales measures when none of its days is covered, or when it contains a gap day, with a partial_range notice. A point that is only partly covered, such as the month that holds the last complete day, is served for its covered days, and partial_range names the covered bounds. Refunds follow a stricter rule: a point whose period runs past refunds_through has refunds: null, with a refunds_partial notice. A month with refunds known through its 12th is null, not a short month. When no day of the range is covered, the sales totals are null, and so is series when the shop has no coverage at all. The notice is then sales_not_covered. reviews doesn’t depend on sales coverage: it’s null only for a point with days after Alura last synced the shop’s reviews, or while they were never synced.

​

A listing’s sales and period

Listing search results and a listing’s detail carry two blocks from the same daily totals:

• sales covers the shop’s whole coverage window: units, revenue, since (the first covered day), last_order_at, and in the detail first_order_at, refund_count and refunds_through. refund_count counts the refunds that touch the listing through refunds_through. sales is null when the shop isn’t covered, has a gap day, or Alura hasn’t finished adding up its totals since new orders arrived. It never uses Etsy’s own sold count for the listing, because Etsy has none per listing.
• period covers the request’s period (7d, 30d, 90d or 365d, each ending yesterday, 30d by default; or all, which spans the shop’s coverage from coverage_from through complete_through) or from/to: from, to, units, orders and revenue. It’s all or nothing: null unless every day of the period is covered. With sort=trending it adds previous_units and change (see Trending listings).

​

Currency

• Listing stats report money as plain numbers in currency: the listing’s own price currency, unless you ask for another with currency=. Money in another currency is converted through US dollars at today’s exchange rates. The response then has conversion (from, to, rate_date, method: "current_rate") and a currency_converted_at_current_rate notice: past sales are converted at today’s rate, not each day’s.
• sales and period give revenue as {amount, currency, usd}: the amount in the orders’ currency, and its US dollar value at today’s rate. When a listing’s sales are in more than one currency, amount and currency are null and only usd is given. A search response’s summary.fx_as_of says the date of the rates.

​

Why shop stats revenue won’t match

Adding up your listings’ period revenue won’t give the revenue of Shop stats for the same days. The two come from different sources:

• Source. Listing numbers come from orders. Shop stats come from the Etsy payment account’s ledger, which Alura stores day by day.
• What revenue holds. Listing revenue is item price minus item discounts. Shop stats revenue is the payment account’s sales after refunds and the taxes Etsy collects.
• Refunds. Listing revenue doesn’t subtract refunds. Shop stats revenue does.
• Days. A sale counts on the day the order was placed. The ledger books money on its own dates.
• Currency. Listing revenue is in the orders’ currency. Shop stats use the payment account’s currency, which can differ from the currency of the shop’s listings.
• Coverage. Each source has its own coverage, so one can know a day the other doesn’t yet.

Use listing numbers to compare listings, and shop stats for the shop’s totals, costs and profit.

​

Version history