> ## Documentation Index > Fetch the complete documentation index at: https://docs.alura.io/llms.txt > Use this file to discover all available pages before exploring further. # Get shop stats > Your connected Etsy shops' sales, costs and profit over a range, from Alura's financials (Etsy's API has no shop stats): revenue, orders, items sold, average order value, refunds, total costs, Etsy fees, marketing, seller services, net profit and margin, and reviews. `expand=` adds revenue detail, fees, marketing, seller services, ratios and balance (the app's 41 financials metrics). `interval=` adds a `series`, `compare=previous_period` the equal period before with the change per metric, `group_by=shop` each shop's own values. Money is in the Etsy payment account's currency (`?currency=` converts at today's rate, as do shops in different currencies, with a notice); ratios are recomputed from the summed amounts. The range defaults to the last 30 days with data. A day without a financials row (a quiet day, or one not yet synced: Alura cannot tell which) is unknown: left out of the totals, a null point, named in a `no_financials_row` notice, never counted as 0, so low-volume shops show null days; days outside a shop's synced data are named in `partial_range`. Known limitation: days synced before a fix to Alura's ledger sync (late 2026) may hold zeros from a failed ledger read that Alura cannot detect. Your own costs (the Costs page) count only once entered. Revenue here comes from the payment ledger, so it does not match a listing's `period` revenue (from orders). Needs the Financial reports workspace permission. Costs 1 API credit per call. Cost: 1 API credit per call. ## OpenAPI ````yaml /openapi.json get /v1/workspace/stats openapi: 3.1.0 info: title: Alura API version: 1.0.0 description: Etsy market research for scripts and AI assistants. servers: - url: https://api.alura.io security: - apiKey: [] paths: /v1/workspace/stats: get: summary: Get shop stats description: >- Your connected Etsy shops' sales, costs and profit over a range, from Alura's financials (Etsy's API has no shop stats): revenue, orders, items sold, average order value, refunds, total costs, Etsy fees, marketing, seller services, net profit and margin, and reviews. `expand=` adds revenue detail, fees, marketing, seller services, ratios and balance (the app's 41 financials metrics). `interval=` adds a `series`, `compare=previous_period` the equal period before with the change per metric, `group_by=shop` each shop's own values. Money is in the Etsy payment account's currency (`?currency=` converts at today's rate, as do shops in different currencies, with a notice); ratios are recomputed from the summed amounts. The range defaults to the last 30 days with data. A day without a financials row (a quiet day, or one not yet synced: Alura cannot tell which) is unknown: left out of the totals, a null point, named in a `no_financials_row` notice, never counted as 0, so low-volume shops show null days; days outside a shop's synced data are named in `partial_range`. Known limitation: days synced before a fix to Alura's ledger sync (late 2026) may hold zeros from a failed ledger read that Alura cannot detect. Your own costs (the Costs page) count only once entered. Revenue here comes from the payment ledger, so it does not match a listing's `period` revenue (from orders). Needs the Financial reports workspace permission. Costs 1 API credit per call. Cost: 1 API credit per call. operationId: workspace.stats.get parameters: - name: shop_id in: query required: false description: >- Only these connected shops, comma-separated; default every connected shop of the workspace. A shop outside the workspace is 404. schema: description: >- Only these connected shops, comma-separated; default every connected shop of the workspace. A shop outside the workspace is 404. type: array items: type: string style: form explode: true - name: period in: query required: false description: >- The last 7, 30, 90 or 365 days, ending on the newest day every included shop has data for. Default `30d`. Not with `from`/`to`. schema: description: >- The last 7, 30, 90 or 365 days, ending on the newest day every included shop has data for. Default `30d`. Not with `from`/`to`. type: string enum: - 7d - 30d - 90d - 365d - name: from in: query required: false description: First day of the range (UTC), inclusive. Needs `to`. schema: type: string pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ description: First day of the range (UTC), inclusive. Needs `to`. - name: to in: query required: false description: Last day of the range (UTC), inclusive. Needs `from`. schema: type: string pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ description: Last day of the range (UTC), inclusive. Needs `from`. - name: interval in: query required: false description: >- Adds `series`, one point per UTC day, week (from Monday), month, quarter or year; at most 366 points. schema: description: >- Adds `series`, one point per UTC day, week (from Monday), month, quarter or year; at most 366 points. type: string enum: - day - week - month - quarter - year example: week - name: compare in: query required: false description: >- `previous_period` adds `compare`: the equal period just before, with the change per metric. schema: description: >- `previous_period` adds `compare`: the equal period just before, with the change per metric. type: string enum: - previous_period example: previous_period - name: group_by in: query required: false description: '`shop` adds `by_shop`, the same values for each shop.' schema: description: '`shop` adds `by_shop`, the same values for each shop.' type: string enum: - shop example: shop - name: currency in: query required: false description: >- Serve the money in this currency, converted at today's rate. Default each shop's own (Etsy payment account) currency. schema: description: >- Serve the money in this currency, converted at today's rate. Default each shop's own (Etsy payment account) currency. type: string pattern: ^[A-Za-z]{3}$ - name: fields in: query required: false description: >- Comma-separated dotted paths to return; `id`, `object` and `as_of` always come back. schema: type: string - name: expand in: query required: false description: >- Comma-separated related objects to include: `revenue_detail`, `fees`, `marketing`, `seller_services`, `ratios`, `balance`. Free. schema: type: string responses: '200': description: OK headers: Request-Id: $ref: '#/components/headers/Request-Id' Alura-Credits-Cost: $ref: '#/components/headers/Alura-Credits-Cost' Alura-Credits-Remaining: $ref: '#/components/headers/Alura-Credits-Remaining' content: application/json: schema: type: object properties: object: type: string const: workspace.stats shop_ids: type: array items: type: string from: type: string to: type: string interval: anyOf: - type: string enum: - day - week - month - quarter - year - type: 'null' currency: description: >- The money's currency; null for a single shop whose Etsy payment account currency is unknown. type: - string - 'null' sales: anyOf: - type: object properties: revenue: type: - number - 'null' orders: type: - number - 'null' units: type: - number - 'null' average_order_value: type: - number - 'null' refunds: type: - number - 'null' refund_count: type: - number - 'null' refund_rate: type: - number - 'null' required: - revenue - orders - units - average_order_value - refunds - refund_count - refund_rate additionalProperties: false description: >- Revenue (Etsy payment account: sales after refunds and taxes Etsy collects), orders, items sold, average order value (gross sales per order), refunds (amount and count) and the refund rate (refunds per order). - type: 'null' costs: anyOf: - type: object properties: total: type: - number - 'null' etsy_fees: type: - number - 'null' marketing: type: - number - 'null' seller_services: type: - number - 'null' required: - total - etsy_fees - marketing - seller_services additionalProperties: false description: >- Total costs (Etsy costs plus your own when you have entered them), Etsy fees, marketing (ads, Etsy Plus, Pattern) and seller services (shipping labels), as positive amounts. - type: 'null' profit: anyOf: - type: object properties: net: type: - number - 'null' margin: type: - number - 'null' net_before_your_costs: type: - number - 'null' required: - net - margin - net_before_your_costs additionalProperties: false description: >- Net profit (revenue minus total costs) and margin (net profit per revenue). `net_before_your_costs`: revenue minus Etsy costs when a shop has no own costs entered (then net profit holds Etsy costs only), else null. - type: 'null' reviews: anyOf: - type: object properties: count: type: - number - 'null' average: type: - number - 'null' rate: type: - number - 'null' required: - count - average - rate additionalProperties: false description: >- Reviews received, their average rating and the review rate (reviews per item sold). - type: 'null' revenue_detail: x-alura-expansion: revenue_detail anyOf: - type: object properties: gross_sales: type: - number - 'null' sales_tax: type: - number - 'null' sales_vat: type: - number - 'null' required: - gross_sales - sales_tax - sales_vat additionalProperties: false description: >- Gross sales, and the sales tax and VAT Etsy collected from buyers. - type: 'null' fees: x-alura-expansion: fees anyOf: - type: object properties: transaction: type: - number - 'null' listing: type: - number - 'null' payments_and_deposit: type: - number - 'null' etsy_costs: type: - number - 'null' your_costs: type: - number - 'null' required: - transaction - listing - payments_and_deposit - etsy_costs - your_costs additionalProperties: false description: >- Etsy fees by kind, all Etsy costs, and your own costs (null when you have entered none). - type: 'null' marketing: x-alura-expansion: marketing anyOf: - type: object properties: ad_spend: type: - number - 'null' etsy_ads: type: - number - 'null' offsite_ads: type: - number - 'null' etsy_plus: type: - number - 'null' pattern: type: - number - 'null' required: - ad_spend - etsy_ads - offsite_ads - etsy_plus - pattern additionalProperties: false description: >- Ad spend (Etsy Ads and Offsite Ads), Etsy Plus and Pattern. - type: 'null' seller_services: x-alura-expansion: seller_services anyOf: - type: object properties: shipping_labels: type: - number - 'null' required: - shipping_labels additionalProperties: false description: Shipping labels bought on Etsy. - type: 'null' ratios: x-alura-expansion: ratios anyOf: - type: object properties: fee_share: type: - number - 'null' marketing_share: type: - number - 'null' seller_services_share: type: - number - 'null' cost_share: type: - number - 'null' etsy_cost_share: type: - number - 'null' etsy_profit: type: - number - 'null' etsy_margin: type: - number - 'null' items_per_order: type: - number - 'null' required: - fee_share - marketing_share - seller_services_share - cost_share - etsy_cost_share - etsy_profit - etsy_margin - items_per_order additionalProperties: false description: >- Each cost as a share of revenue, Etsy-only profit and margin (before your own costs), and items per order. - type: 'null' balance: x-alura-expansion: balance anyOf: - type: object properties: payments_to_etsy: type: - number - 'null' payments_from_etsy: type: - number - 'null' closing: type: - number - 'null' required: - payments_to_etsy - payments_from_etsy - closing additionalProperties: false description: >- Payments to and from Etsy (positive amounts) and the payment account balance on the last day. - type: 'null' series: type: array items: type: object properties: period: type: string description: >- `2026-09-14` (day, or the week from that Monday), `2026-09`, `2026-Q3` or `2026`. from: type: string to: type: string sales: anyOf: - type: object properties: revenue: type: - number - 'null' orders: type: - number - 'null' units: type: - number - 'null' average_order_value: type: - number - 'null' refunds: type: - number - 'null' refund_count: type: - number - 'null' refund_rate: type: - number - 'null' required: - revenue - orders - units - average_order_value - refunds - refund_count - refund_rate additionalProperties: false description: >- Revenue (Etsy payment account: sales after refunds and taxes Etsy collects), orders, items sold, average order value (gross sales per order), refunds (amount and count) and the refund rate (refunds per order). - type: 'null' costs: anyOf: - type: object properties: total: type: - number - 'null' etsy_fees: type: - number - 'null' marketing: type: - number - 'null' seller_services: type: - number - 'null' required: - total - etsy_fees - marketing - seller_services additionalProperties: false description: >- Total costs (Etsy costs plus your own when you have entered them), Etsy fees, marketing (ads, Etsy Plus, Pattern) and seller services (shipping labels), as positive amounts. - type: 'null' profit: anyOf: - type: object properties: net: type: - number - 'null' margin: type: - number - 'null' net_before_your_costs: type: - number - 'null' required: - net - margin - net_before_your_costs additionalProperties: false description: >- Net profit (revenue minus total costs) and margin (net profit per revenue). `net_before_your_costs`: revenue minus Etsy costs when a shop has no own costs entered (then net profit holds Etsy costs only), else null. - type: 'null' reviews: anyOf: - type: object properties: count: type: - number - 'null' average: type: - number - 'null' rate: type: - number - 'null' required: - count - average - rate additionalProperties: false description: >- Reviews received, their average rating and the review rate (reviews per item sold). - type: 'null' revenue_detail: x-alura-expansion: revenue_detail anyOf: - type: object properties: gross_sales: type: - number - 'null' sales_tax: type: - number - 'null' sales_vat: type: - number - 'null' required: - gross_sales - sales_tax - sales_vat additionalProperties: false description: >- Gross sales, and the sales tax and VAT Etsy collected from buyers. - type: 'null' fees: x-alura-expansion: fees anyOf: - type: object properties: transaction: type: - number - 'null' listing: type: - number - 'null' payments_and_deposit: type: - number - 'null' etsy_costs: type: - number - 'null' your_costs: type: - number - 'null' required: - transaction - listing - payments_and_deposit - etsy_costs - your_costs additionalProperties: false description: >- Etsy fees by kind, all Etsy costs, and your own costs (null when you have entered none). - type: 'null' marketing: x-alura-expansion: marketing anyOf: - type: object properties: ad_spend: type: - number - 'null' etsy_ads: type: - number - 'null' offsite_ads: type: - number - 'null' etsy_plus: type: - number - 'null' pattern: type: - number - 'null' required: - ad_spend - etsy_ads - offsite_ads - etsy_plus - pattern additionalProperties: false description: >- Ad spend (Etsy Ads and Offsite Ads), Etsy Plus and Pattern. - type: 'null' seller_services: x-alura-expansion: seller_services anyOf: - type: object properties: shipping_labels: type: - number - 'null' required: - shipping_labels additionalProperties: false description: Shipping labels bought on Etsy. - type: 'null' ratios: x-alura-expansion: ratios anyOf: - type: object properties: fee_share: type: - number - 'null' marketing_share: type: - number - 'null' seller_services_share: type: - number - 'null' cost_share: type: - number - 'null' etsy_cost_share: type: - number - 'null' etsy_profit: type: - number - 'null' etsy_margin: type: - number - 'null' items_per_order: type: - number - 'null' required: - fee_share - marketing_share - seller_services_share - cost_share - etsy_cost_share - etsy_profit - etsy_margin - items_per_order additionalProperties: false description: >- Each cost as a share of revenue, Etsy-only profit and margin (before your own costs), and items per order. - type: 'null' balance: x-alura-expansion: balance anyOf: - type: object properties: payments_to_etsy: type: - number - 'null' payments_from_etsy: type: - number - 'null' closing: type: - number - 'null' required: - payments_to_etsy - payments_from_etsy - closing additionalProperties: false description: >- Payments to and from Etsy (positive amounts) and the payment account balance on the last day. - type: 'null' required: - period - from - to - sales - costs - profit - reviews additionalProperties: false compare: type: object properties: from: type: string to: type: string sales: anyOf: - type: object properties: revenue: type: - number - 'null' orders: type: - number - 'null' units: type: - number - 'null' average_order_value: type: - number - 'null' refunds: type: - number - 'null' refund_count: type: - number - 'null' refund_rate: type: - number - 'null' required: - revenue - orders - units - average_order_value - refunds - refund_count - refund_rate additionalProperties: false description: >- Revenue (Etsy payment account: sales after refunds and taxes Etsy collects), orders, items sold, average order value (gross sales per order), refunds (amount and count) and the refund rate (refunds per order). - type: 'null' costs: anyOf: - type: object properties: total: type: - number - 'null' etsy_fees: type: - number - 'null' marketing: type: - number - 'null' seller_services: type: - number - 'null' required: - total - etsy_fees - marketing - seller_services additionalProperties: false description: >- Total costs (Etsy costs plus your own when you have entered them), Etsy fees, marketing (ads, Etsy Plus, Pattern) and seller services (shipping labels), as positive amounts. - type: 'null' profit: anyOf: - type: object properties: net: type: - number - 'null' margin: type: - number - 'null' net_before_your_costs: type: - number - 'null' required: - net - margin - net_before_your_costs additionalProperties: false description: >- Net profit (revenue minus total costs) and margin (net profit per revenue). `net_before_your_costs`: revenue minus Etsy costs when a shop has no own costs entered (then net profit holds Etsy costs only), else null. - type: 'null' reviews: anyOf: - type: object properties: count: type: - number - 'null' average: type: - number - 'null' rate: type: - number - 'null' required: - count - average - rate additionalProperties: false description: >- Reviews received, their average rating and the review rate (reviews per item sold). - type: 'null' revenue_detail: x-alura-expansion: revenue_detail anyOf: - type: object properties: gross_sales: type: - number - 'null' sales_tax: type: - number - 'null' sales_vat: type: - number - 'null' required: - gross_sales - sales_tax - sales_vat additionalProperties: false description: >- Gross sales, and the sales tax and VAT Etsy collected from buyers. - type: 'null' fees: x-alura-expansion: fees anyOf: - type: object properties: transaction: type: - number - 'null' listing: type: - number - 'null' payments_and_deposit: type: - number - 'null' etsy_costs: type: - number - 'null' your_costs: type: - number - 'null' required: - transaction - listing - payments_and_deposit - etsy_costs - your_costs additionalProperties: false description: >- Etsy fees by kind, all Etsy costs, and your own costs (null when you have entered none). - type: 'null' marketing: x-alura-expansion: marketing anyOf: - type: object properties: ad_spend: type: - number - 'null' etsy_ads: type: - number - 'null' offsite_ads: type: - number - 'null' etsy_plus: type: - number - 'null' pattern: type: - number - 'null' required: - ad_spend - etsy_ads - offsite_ads - etsy_plus - pattern additionalProperties: false description: >- Ad spend (Etsy Ads and Offsite Ads), Etsy Plus and Pattern. - type: 'null' seller_services: x-alura-expansion: seller_services anyOf: - type: object properties: shipping_labels: type: - number - 'null' required: - shipping_labels additionalProperties: false description: Shipping labels bought on Etsy. - type: 'null' ratios: x-alura-expansion: ratios anyOf: - type: object properties: fee_share: type: - number - 'null' marketing_share: type: - number - 'null' seller_services_share: type: - number - 'null' cost_share: type: - number - 'null' etsy_cost_share: type: - number - 'null' etsy_profit: type: - number - 'null' etsy_margin: type: - number - 'null' items_per_order: type: - number - 'null' required: - fee_share - marketing_share - seller_services_share - cost_share - etsy_cost_share - etsy_profit - etsy_margin - items_per_order additionalProperties: false description: >- Each cost as a share of revenue, Etsy-only profit and margin (before your own costs), and items per order. - type: 'null' balance: x-alura-expansion: balance anyOf: - type: object properties: payments_to_etsy: type: - number - 'null' payments_from_etsy: type: - number - 'null' closing: type: - number - 'null' required: - payments_to_etsy - payments_from_etsy - closing additionalProperties: false description: >- Payments to and from Etsy (positive amounts) and the payment account balance on the last day. - type: 'null' change: type: object propertyNames: type: string additionalProperties: type: - number - 'null' description: >- The relative change of each metric, `sales.revenue`: 0.12 for 12% more; null when either value is unknown or the earlier one is 0. coverage: type: array items: type: object properties: shop_id: type: string from: type: - string - 'null' through: type: - string - 'null' required: - shop_id - from - through additionalProperties: false description: >- A shop's stats data: its first day and its last complete day (the day before its newest full sync whose ledger and financials both succeeded); null when it has none. required: - from - to - sales - costs - profit - reviews - change - coverage additionalProperties: false by_shop: type: array items: type: object properties: shop_id: type: string currency: type: - string - 'null' sales: anyOf: - type: object properties: revenue: type: - number - 'null' orders: type: - number - 'null' units: type: - number - 'null' average_order_value: type: - number - 'null' refunds: type: - number - 'null' refund_count: type: - number - 'null' refund_rate: type: - number - 'null' required: - revenue - orders - units - average_order_value - refunds - refund_count - refund_rate additionalProperties: false description: >- Revenue (Etsy payment account: sales after refunds and taxes Etsy collects), orders, items sold, average order value (gross sales per order), refunds (amount and count) and the refund rate (refunds per order). - type: 'null' costs: anyOf: - type: object properties: total: type: - number - 'null' etsy_fees: type: - number - 'null' marketing: type: - number - 'null' seller_services: type: - number - 'null' required: - total - etsy_fees - marketing - seller_services additionalProperties: false description: >- Total costs (Etsy costs plus your own when you have entered them), Etsy fees, marketing (ads, Etsy Plus, Pattern) and seller services (shipping labels), as positive amounts. - type: 'null' profit: anyOf: - type: object properties: net: type: - number - 'null' margin: type: - number - 'null' net_before_your_costs: type: - number - 'null' required: - net - margin - net_before_your_costs additionalProperties: false description: >- Net profit (revenue minus total costs) and margin (net profit per revenue). `net_before_your_costs`: revenue minus Etsy costs when a shop has no own costs entered (then net profit holds Etsy costs only), else null. - type: 'null' reviews: anyOf: - type: object properties: count: type: - number - 'null' average: type: - number - 'null' rate: type: - number - 'null' required: - count - average - rate additionalProperties: false description: >- Reviews received, their average rating and the review rate (reviews per item sold). - type: 'null' revenue_detail: x-alura-expansion: revenue_detail anyOf: - type: object properties: gross_sales: type: - number - 'null' sales_tax: type: - number - 'null' sales_vat: type: - number - 'null' required: - gross_sales - sales_tax - sales_vat additionalProperties: false description: >- Gross sales, and the sales tax and VAT Etsy collected from buyers. - type: 'null' fees: x-alura-expansion: fees anyOf: - type: object properties: transaction: type: - number - 'null' listing: type: - number - 'null' payments_and_deposit: type: - number - 'null' etsy_costs: type: - number - 'null' your_costs: type: - number - 'null' required: - transaction - listing - payments_and_deposit - etsy_costs - your_costs additionalProperties: false description: >- Etsy fees by kind, all Etsy costs, and your own costs (null when you have entered none). - type: 'null' marketing: x-alura-expansion: marketing anyOf: - type: object properties: ad_spend: type: - number - 'null' etsy_ads: type: - number - 'null' offsite_ads: type: - number - 'null' etsy_plus: type: - number - 'null' pattern: type: - number - 'null' required: - ad_spend - etsy_ads - offsite_ads - etsy_plus - pattern additionalProperties: false description: >- Ad spend (Etsy Ads and Offsite Ads), Etsy Plus and Pattern. - type: 'null' seller_services: x-alura-expansion: seller_services anyOf: - type: object properties: shipping_labels: type: - number - 'null' required: - shipping_labels additionalProperties: false description: Shipping labels bought on Etsy. - type: 'null' ratios: x-alura-expansion: ratios anyOf: - type: object properties: fee_share: type: - number - 'null' marketing_share: type: - number - 'null' seller_services_share: type: - number - 'null' cost_share: type: - number - 'null' etsy_cost_share: type: - number - 'null' etsy_profit: type: - number - 'null' etsy_margin: type: - number - 'null' items_per_order: type: - number - 'null' required: - fee_share - marketing_share - seller_services_share - cost_share - etsy_cost_share - etsy_profit - etsy_margin - items_per_order additionalProperties: false description: >- Each cost as a share of revenue, Etsy-only profit and margin (before your own costs), and items per order. - type: 'null' balance: x-alura-expansion: balance anyOf: - type: object properties: payments_to_etsy: type: - number - 'null' payments_from_etsy: type: - number - 'null' closing: type: - number - 'null' required: - payments_to_etsy - payments_from_etsy - closing additionalProperties: false description: >- Payments to and from Etsy (positive amounts) and the payment account balance on the last day. - type: 'null' required: - shop_id - currency - sales - costs - profit - reviews additionalProperties: false conversion: anyOf: - type: object properties: from: type: array items: type: string to: type: string rate_date: type: string method: type: string const: current_rate required: - from - to - rate_date - method additionalProperties: false - type: 'null' description: >- What was converted: from these currencies into `to`, all history at the rate of `rate_date` (today's rates, not each day's). null when nothing was converted. coverage: type: array items: type: object properties: shop_id: type: string from: type: - string - 'null' through: type: - string - 'null' required: - shop_id - from - through additionalProperties: false description: >- A shop's stats data: its first day and its last complete day (the day before its newest full sync whose ledger and financials both succeeded); null when it has none. as_of: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ - type: 'null' description: The oldest included shop's financials sync time. freshness: type: array items: type: object properties: shop_id: type: string as_of: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ - type: 'null' required: - shop_id - as_of additionalProperties: false notices: type: array items: type: object properties: code: type: string description: >- `stale_shops`, `partial_range`, `no_financials_row`, `metric_unavailable`, `your_costs_missing`, `currency_converted_at_current_rate` or `currency_unknown`. New codes may be added. shop_ids: type: array items: type: string detail: type: string missing: anyOf: - type: array items: type: object properties: shop_id: type: string from: type: string to: type: string required: - shop_id - from - to additionalProperties: false - type: 'null' description: >- `partial_range` and `no_financials_row`: the days without data, per shop (`metric_unavailable`: the days a metric has no value); null for other notices. metrics: anyOf: - type: array items: type: string - type: 'null' description: >- `metric_unavailable`: the metrics (`sales.units`) a missing value makes null; null for other notices. required: - code - shop_ids - detail - missing - metrics additionalProperties: false required: - object - shop_ids - from - to - interval - currency - sales - costs - profit - reviews - conversion - coverage - as_of - freshness - notices additionalProperties: false example: object: workspace.stats shop_ids: - '22841907' - '30577120' - '48911633' from: '2026-09-08' to: '2026-10-07' interval: week currency: USD sales: revenue: 10182.93 orders: 423 units: 483 average_order_value: 25.94 refunds: 131.33 refund_count: 5 refund_rate: 0.0118 costs: total: 2419.82 etsy_fees: 1256.43 marketing: 297.24 seller_services: 806.15 profit: net: 7763.11 margin: 0.7624 net_before_your_costs: 7823.11 reviews: count: 15 average: 5 rate: 0.0311 series: - period: '2026-09-07' from: '2026-09-08' to: '2026-09-13' sales: revenue: 1937.56 orders: 81 units: 93 average_order_value: 25.81 refunds: 27.44 refund_count: 1 refund_rate: 0.0123 costs: total: 446.5 etsy_fees: 239.49 marketing: 53.43 seller_services: 153.58 profit: net: 1491.06 margin: 0.7696 net_before_your_costs: 1491.06 reviews: count: 3 average: 5 rate: 0.0323 - period: '2026-09-14' from: '2026-09-14' to: '2026-09-20' sales: revenue: 2554.98 orders: 106 units: 122 average_order_value: 25.89 refunds: 24.5 refund_count: 1 refund_rate: 0.0094 costs: total: 600.79 etsy_fees: 314.43 marketing: 69.75 seller_services: 201.61 profit: net: 1954.19 margin: 0.7649 net_before_your_costs: 1969.19 reviews: count: 4 average: 5 rate: 0.0328 - period: '2026-09-21' from: '2026-09-21' to: '2026-09-27' sales: revenue: 2332.8 orders: 96 units: 108 average_order_value: 26.16 refunds: 27.44 refund_count: 1 refund_rate: 0.0104 costs: total: 547.47 etsy_fees: 287.15 marketing: 60.85 seller_services: 184.47 profit: net: 1785.34 margin: 0.7653 net_before_your_costs: 1800.34 reviews: count: 3 average: 5 rate: 0.0278 - period: '2026-09-28' from: '2026-09-28' to: '2026-10-04' sales: revenue: 2298.89 orders: 95 units: 109 average_order_value: 26.02 refunds: 24.5 refund_count: 1 refund_rate: 0.0105 costs: total: 565.96 etsy_fees: 283.12 marketing: 86.25 seller_services: 181.59 profit: net: 1732.92 margin: 0.7538 net_before_your_costs: 1747.92 reviews: count: 4 average: 5 rate: 0.0367 - period: '2026-10-05' from: '2026-10-05' to: '2026-10-07' sales: revenue: 1058.7 orders: 45 units: 51 average_order_value: 25.68 refunds: 27.44 refund_count: 1 refund_rate: 0.0222 costs: total: 259.1 etsy_fees: 132.25 marketing: 26.97 seller_services: 84.89 profit: net: 799.59 margin: 0.7553 net_before_your_costs: 814.59 reviews: count: 1 average: 5 rate: 0.0196 compare: from: '2026-08-09' to: '2026-09-07' sales: revenue: 10183.32 orders: 423 units: 483 average_order_value: 26 refunds: 155.83 refund_count: 6 refund_rate: 0.0142 costs: total: 2439.76 etsy_fees: 1259.42 marketing: 297.24 seller_services: 808.1 profit: net: 7743.56 margin: 0.7604 net_before_your_costs: 7818.56 reviews: count: 15 average: 5 rate: 0.0311 change: sales.revenue: 0 sales.orders: 0 sales.units: 0 sales.average_order_value: -0.0023 sales.refunds: -0.1572 sales.refund_count: -0.1667 sales.refund_rate: -0.169 costs.total: -0.0082 costs.etsy_fees: -0.0024 costs.marketing: 0 costs.seller_services: -0.0024 profit.net: 0.0025 profit.margin: 0.0026 profit.net_before_your_costs: 0.0006 reviews.count: 0 reviews.average: 0 reviews.rate: 0 coverage: - shop_id: '22841907' from: '2021-10-01' through: '2026-10-07' - shop_id: '30577120' from: null through: '2026-10-16' - shop_id: '48911633' from: '2022-03-01' through: '2026-10-15' by_shop: - shop_id: '22841907' currency: USD sales: revenue: 4925.48 orders: 216 units: 246 average_order_value: 24.5 refunds: 49 refund_count: 2 refund_rate: 0.0093 costs: total: 1194.83 etsy_fees: 605.83 marketing: 140.2 seller_services: 388.8 profit: net: 3730.65 margin: 0.7574 net_before_your_costs: null reviews: count: 7 average: 5 rate: 0.0285 - shop_id: '30577120' currency: USD sales: null costs: null profit: null reviews: null - shop_id: '48911633' currency: USD sales: revenue: 5257.45 orders: 207 units: 237 average_order_value: 27.44 refunds: 82.33 refund_count: 3 refund_rate: 0.0145 costs: total: 1224.99 etsy_fees: 650.6 marketing: 157.04 seller_services: 417.35 profit: net: 4032.46 margin: 0.767 net_before_your_costs: 4032.46 reviews: count: 8 average: 5 rate: 0.0338 conversion: from: - EUR to: USD rate_date: '2026-10-14' method: current_rate coverage: - shop_id: '22841907' from: '2021-10-01' through: '2026-10-07' - shop_id: '30577120' from: null through: '2026-10-16' - shop_id: '48911633' from: '2022-03-01' through: '2026-10-15' as_of: '2026-10-08T06:00:00.000Z' freshness: - shop_id: '22841907' as_of: '2026-10-08T06:00:00.000Z' - shop_id: '30577120' as_of: '2026-10-17T06:00:00.000Z' - shop_id: '48911633' as_of: '2026-10-16T06:00:00.000Z' notices: - code: stale_shops shop_ids: - '22841907' detail: >- These shops have no data, or no data newer than 7 days, for this area. Start a sync to refresh them. missing: null metrics: null - code: partial_range shop_ids: - '30577120' detail: >- These days of the range (or of the compare period) are outside these shops' stats: before their first financials day, or after their last complete sync. Totals leave them out; a series point without any data is null, and so is a closing balance whose last day is one of them. missing: - shop_id: '30577120' from: '2026-08-09' to: '2026-09-07' - shop_id: '30577120' from: '2026-09-08' to: '2026-10-07' metrics: null - code: your_costs_missing shop_ids: - '48911633' detail: >- These shops have no own costs entered in Alura (the Costs page), so costs.total and profit.net hold Etsy costs only; profit.net_before_your_costs is revenue minus Etsy costs. missing: null metrics: null - code: currency_converted_at_current_rate shop_ids: - '48911633' detail: >- Money of these shops was converted into USD at the rate of 2026-10-14: history is converted at that rate, not each day's. missing: null metrics: null '400': $ref: '#/components/responses/Problem400' '401': $ref: '#/components/responses/Problem401' '402': $ref: '#/components/responses/Problem402' '403': $ref: '#/components/responses/Problem403' '404': $ref: '#/components/responses/Problem404' '405': $ref: '#/components/responses/Problem405' '429': $ref: '#/components/responses/Problem429' '500': $ref: '#/components/responses/Problem500' '503': $ref: '#/components/responses/Problem503' x-codeSamples: - lang: bash label: cURL source: >- curl "https://api.alura.io/v1/workspace/stats?interval=week&compare=previous_period&group_by=shop" \ -H "Authorization: Bearer $ALURA_API_KEY" - lang: typescript label: TypeScript source: >- const res = await fetch('https://api.alura.io/v1/workspace/stats?interval=week&compare=previous_period&group_by=shop', { headers: { Authorization: `Bearer ${process.env.ALURA_API_KEY}`, }, }); console.log(await res.json()); - lang: python label: Python source: |- import json import os import urllib.request request = urllib.request.Request( "https://api.alura.io/v1/workspace/stats?interval=week&compare=previous_period&group_by=shop", headers={ "Authorization": f"Bearer {os.environ['ALURA_API_KEY']}", }, ) with urllib.request.urlopen(request) as response: print(json.load(response)) components: headers: Request-Id: description: '`req_` + ULID; quote it when reporting a problem.' schema: type: string Alura-Credits-Cost: description: API credits this call cost. schema: type: integer Alura-Credits-Remaining: description: >- API credits left in the workspace's monthly allowance, counting calls still in flight. Absent when it cannot be read right now. schema: type: integer responses: Problem400: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/invalid_request title: Invalid request status: 400 code: invalid_request detail: Invalid request suggestion: Fix the request as the detail says, then send it again. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem401: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/unauthorized title: Unauthorized status: 401 code: unauthorized detail: Unauthorized suggestion: 'Send a valid API key as `Authorization: Bearer alura_sk_...`.' retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem402: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/credits_exhausted title: API credits exhausted status: 402 code: credits_exhausted detail: API credits exhausted suggestion: Upgrade the plan or wait for the monthly reset. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem403: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/plan_required title: Plan required status: 403 code: plan_required detail: Plan required suggestion: Upgrade the workspace plan to use this operation. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem404: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/not_found title: Not found status: 404 code: not_found detail: Not found suggestion: Check the ID, or search for it first. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem405: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/method_not_allowed title: Method not allowed status: 405 code: method_not_allowed detail: Method not allowed suggestion: Use one of the methods in the Allow header. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem429: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/rate_limited title: Rate limited status: 429 code: rate_limited detail: Rate limited suggestion: Wait for Retry-After, then retry. retryable: true request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem500: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/internal_error title: Internal error status: 500 code: internal_error detail: Internal error suggestion: Retry; if it keeps failing, report the request_id. retryable: true request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem503: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/credits_unavailable title: API credits unavailable status: 503 code: credits_unavailable detail: API credits unavailable suggestion: Retry shortly. retryable: true request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B schemas: Problem: type: object description: RFC 9457 problem details. properties: type: type: string format: uri title: type: string status: type: integer code: type: string description: A code from the error catalog; new codes may be added. x-extensible-enum: - invalid_request - unknown_parameter - invalid_cursor - cursor_window_exceeded - invalid_reference - id_type_mismatch - invalid_keyword - shop_id_required - sales_window_not_covered - unauthorized - credits_exhausted - plan_required - insufficient_scope - workspace_required - workspace_locked - browser_refused - role_required - impersonation_refused - recent_sign_in_required - etsy_scope_required - etsy_partner_required - not_found - not_found_on_etsy - shop_opted_out - method_not_allowed - conflict - key_limit_reached - reconnect_required - listing_busy - shop_create_busy - idempotency_partial_unverifiable - activation_skipped - idempotency_processing - unprocessable - listing_removed_on_etsy - rate_limited - throttled - daily_credit_cap_exceeded - credits_reserved - fetch_limit_reached - sync_cooldown - shop_write_budget_exhausted - internal_error - write_misconfigured - upstream_unavailable - credits_unavailable - service_unavailable - fetch_unavailable - create_lock_unavailable - etsy_capacity - upstream_timeout detail: type: string suggestion: type: string retryable: type: boolean request_id: type: string upgrade_url: type: string format: uri description: 'credits_exhausted and plan_required: where to upgrade the plan.' credits_needed: type: integer description: 'API credit refusals: what the call needed.' credits_remaining: type: integer description: >- API credit refusals: what is left (of the month, or of the day for daily_credit_cap_exceeded). resets_at: type: string format: date-time description: >- credits_exhausted and daily_credit_cap_exceeded: when the limit resets. required: - type - title - status - code - detail - suggestion - retryable - request_id securitySchemes: apiKey: type: http scheme: bearer description: 'An API key: `Authorization: Bearer alura_sk_...`.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.