> ## 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 variation stats > Get which variants of your connected shops' listings sell: for each listing, each combination of options buyers chose, with items sold and orders, and refunded items and orders apart. **Cost:** 1 API credit per call. ```bash curl -G "https://api.alura.io/v1/workspace/stats/variations" \ -H "Authorization: Bearer $ALURA_API_KEY" \ --data-urlencode "period=90d" ``` Covers every connected shop in the workspace unless `shop_id` narrows it, and every listing that sold unless `listing_id` names up to 50 (comma-separated). Listings you name are picked before the ranking and the limits, so they are never left out. A shop or listing outside the workspace answers `404`. Needs the **Customer analytics** workspace permission, as orders do. Until 2026-11-10 this endpoint's path was `/v1/workspace/variation-sales`, which now answers `410 endpoint_removed`. ## Choose the range | You want | Use | | - | - | | The last 7, 30, 90 or 365 days | `period=7d`, `30d`, `90d` or `365d`, ending on the newest day every included shop's orders are complete for, as [Get shop stats](https://docs.alura.io/api-reference/workspace/stats/get.md) ends its period. The default is `30d`. | | Exact days | `from` and `to`, such as `from=2026-07-01&to=2026-09-30`. Both are inclusive UTC days, at most 366 days. | An order counts on the day it was placed. `from` and `to` go together, and never with `period`: any other mix answers `400`. Days are UTC, not Etsy's US Eastern days, so a single day can differ from Etsy Shop Manager. ## What the answer holds `listings` holds each listing sold in the range, most orders first. Each listing has: | Field | What it means | | - | - | | `units`, `orders` | Items sold, and orders with at least one of them. | | `refunded_units`, `refunded_orders` | The same, for orders that have a refund. Etsy records a refund on the order, not on an item, so a partial refund counts every item of the order. | | `variations` | Each combination of options sold, such as `Color: Blue` with `Size: Large`, most orders first, with the same four numbers. Items sold without options are the combination `[]`. | | `unknown` | What sold on order lines whose options Alura doesn't know (see below), with the same four numbers. | | `coverage` | How many order lines the listing had in the range: `known` make up `variations`, `unknown` make up `unknown`. | The top-level `coverage` counts the same over every included shop. `freshness` and `as_of` say when each shop's orders were synced. An order with two items of one listing in different options counts once in the listing's `orders` and once in each combination's. So a listing's `orders` can be less than the sum of its combinations'. ## Unknown options > [!NOTE] > > A line whose options Alura hasn't stored yet, or can't read, is unknown: it never counts as "no options". It is counted in `coverage.unknown` and in its listing's `unknown`, never in a combination. Compare `coverage.known` with `coverage.lines` before you rank combinations. A `null` unit count means one of its order lines has no quantity in Alura. It is never counted as 0. Personalization answers are never part of a combination or of this answer. To read them, use [Get an order](https://docs.alura.io/api-reference/workspace/orders/get.md). > [accordion] Limits > > At most 100 listings, each with at most 100 combinations. `listings_omitted` and each listing's `variations_omitted` count the rest. Ask for fewer shops, a shorter range, or name the listings with `listing_id` to see them. A range whose shops sold more than 20,000 listing and option combinations answers `400`. > [accordion] Money > > This endpoint counts items and orders, not money. For revenue, costs and profit, use [Get shop stats](https://docs.alura.io/api-reference/workspace/stats/get.md). ## OpenAPI ````yaml /openapi.json get /v1/workspace/stats/variations 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/variations: get: summary: Get variation stats description: >- Which variants of your connected Etsy shops' listings sell, over a range of days (default the last 30). Each listing's option combinations (such as `Color: Blue, Size: Large`) are counted from the order lines of orders placed in the range: items sold, orders, and separately the items and orders that have a refund (Etsy records a refund on the order, not the item). Items sold without options are the combination `[]`. A line whose options Alura has not stored yet, or cannot read, is unknown: counted in `coverage.unknown` and in its listing's `unknown`, never in a combination and never as "no options". Personalization answers are never part of a combination or of this answer. Money is not included. The range is read as shop stats read theirs: `period` ends on the newest day every included shop's orders are complete for, or give `from`/`to`. Listings come most orders first, at most 100, each with at most 100 combinations; `listings_omitted` and `variations_omitted` count the rest. `listing_id` (up to 50) picks listings before the ranking and the limits. A range holds at most 366 days. Needs the Customer analytics workspace permission. Costs 1 API credit per call. Days are UTC, not Etsy's own (US Eastern) days, so a single day can differ from Etsy Shop Manager. Cost: 1 API credit per call. operationId: workspace.stats.variations 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: listing_id in: query required: false description: >- Only these listings, comma-separated (at most 50); default every listing that sold. They are chosen before the ranking and the limits, so a listing named is never left out. A listing outside the workspace is 404. schema: description: >- Only these listings, comma-separated (at most 50); default every listing that sold. They are chosen before the ranking and the limits, so a listing named is never left out. A listing outside the workspace is 404. type: array items: type: string style: form explode: true - name: period in: query required: false description: >- `7d`, `30d`, `90d` or `365d`: the last 7, 30, 90 or 365 days, ending on the newest day every included shop's orders are complete for (as shop stats end theirs). Default `30d`. Not with `from`/`to`. schema: description: >- `7d`, `30d`, `90d` or `365d`: the last 7, 30, 90 or 365 days, ending on the newest day every included shop's orders are complete for (as shop stats end theirs). Default `30d`. Not with `from`/`to`. type: string enum: - 7d - 30d - 90d - 365d example: 90d - 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`; at most 366 days after it. schema: type: string pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ description: >- Last day of the range (UTC), inclusive. Needs `from`; at most 366 days after it. - name: fields in: query required: false description: >- Comma-separated dotted paths to return; `id`, `object` and `as_of` always come back. 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.variation_stats shop_ids: type: array items: type: string description: The connected shops included. from: type: string description: The range's first day (UTC). to: type: string description: The range's last day (UTC). listings: type: array items: type: object properties: listing_id: description: >- The Etsy listing; null for lines Etsy gave without one. type: - string - 'null' shop_id: type: string description: The connected shop. units: anyOf: - type: integer - type: 'null' description: Items sold. null when a line's quantity is unknown. orders: type: integer description: Orders with at least one of these items. refunded_units: anyOf: - type: integer - type: 'null' description: >- Items sold in orders that have a refund. Etsy records a refund on the order, not the item, so a partial refund counts every item of the order. null when a line's quantity is unknown. refunded_orders: type: integer description: >- Orders with at least one of these items that have a refund. coverage: type: object properties: lines: type: integer description: >- Order lines (one per listing per order) in the range. known: type: integer description: >- Lines whose options Alura has stored: they make up `variations`. unknown: type: integer description: >- Lines whose options Alura has not stored yet, or cannot read: they make up `unknown`, never a combination. required: - lines - known - unknown additionalProperties: false description: How many order lines the combinations account for. variations: type: array items: type: object properties: options: type: array items: type: object properties: name: type: string description: The variation, such as `Color`. value: type: string description: The value chosen. required: - name - value additionalProperties: false description: >- The options chosen, sorted by name: `[]` for items sold without options. units: anyOf: - type: integer - type: 'null' description: >- Items sold. null when a line's quantity is unknown. orders: type: integer description: Orders with at least one of these items. refunded_units: anyOf: - type: integer - type: 'null' description: >- Items sold in orders that have a refund. Etsy records a refund on the order, not the item, so a partial refund counts every item of the order. null when a line's quantity is unknown. refunded_orders: type: integer description: >- Orders with at least one of these items that have a refund. required: - options - units - orders - refunded_units - refunded_orders additionalProperties: false description: One combination of options, and what sold with it. description: Each combination sold, most orders first. variations_omitted: type: integer description: >- Combinations left out of `variations` past the limit. unknown: type: object properties: units: anyOf: - type: integer - type: 'null' description: >- Items sold. null when a line's quantity is unknown. orders: type: integer description: Orders with at least one of these items. refunded_units: anyOf: - type: integer - type: 'null' description: >- Items sold in orders that have a refund. Etsy records a refund on the order, not the item, so a partial refund counts every item of the order. null when a line's quantity is unknown. refunded_orders: type: integer description: >- Orders with at least one of these items that have a refund. required: - units - orders - refunded_units - refunded_orders additionalProperties: false description: >- What sold on the lines whose options are unknown (`coverage.unknown`): not a combination, and never "no options". required: - listing_id - shop_id - units - orders - refunded_units - refunded_orders - coverage - variations - variations_omitted - unknown additionalProperties: false description: Each listing sold in the range, most orders first. listings_omitted: type: integer description: Listings left out of `listings` past the limit. coverage: type: object properties: lines: type: integer description: Order lines (one per listing per order) in the range. known: type: integer description: >- Lines whose options Alura has stored: they make up `variations`. unknown: type: integer description: >- Lines whose options Alura has not stored yet, or cannot read: they make up `unknown`, never a combination. required: - lines - known - unknown additionalProperties: false description: >- How many order lines in the range, over every included shop, the combinations account for. 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 orders sync time. freshness: type: array items: type: object properties: shop_id: type: string description: The connected shop. 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 shop's orders sync time. required: - shop_id - as_of additionalProperties: false description: Each included shop's orders sync time. notices: type: array items: type: object properties: code: type: string description: >- `stale_shops`, `sales_not_covered`, `partial_range`, `settings_not_fetched`, `holiday_settings_not_offered`, `settings_sections_only`, `listings_count_unavailable`, `listings_not_synced`, `shipping_cost_inexact`, `sales_through`, `refunds_partial`, `unknown_sales_inputs`, `sync_daily_cap_reached`, `currency_converted_at_current_rate`, `reviews_not_synced`, `reviews_stale`, `customers_not_computed`, `lifetime_value_ranked_by_stored_total`, `refunds_unknown`, `lifetime_value_unknown`, `items_unknown` or `search_incomplete`. New codes may be added. shop_ids: type: array items: type: string description: The shops the notice is about. detail: type: string required: - code - shop_ids - detail additionalProperties: false description: What is stale; empty when nothing is. required: - object - shop_ids - from - to - listings - listings_omitted - coverage - as_of - freshness - notices additionalProperties: false example: object: workspace.variation_stats shop_ids: - '22841907' - '30577120' - '48911633' from: '2026-07-10' to: '2026-10-07' listings: - listing_id: '1834720561' shop_id: '22841907' units: 2 orders: 1 refunded_units: 0 refunded_orders: 0 coverage: lines: 1 known: 1 unknown: 0 variations: - options: - name: Primary color value: White - name: Size value: 11 oz units: 2 orders: 1 refunded_units: 0 refunded_orders: 0 variations_omitted: 0 unknown: units: 0 orders: 0 refunded_units: 0 refunded_orders: 0 - listing_id: '1834720562' shop_id: '22841907' units: 1 orders: 1 refunded_units: 1 refunded_orders: 1 coverage: lines: 1 known: 1 unknown: 0 variations: - options: - name: Primary color value: Black units: 1 orders: 1 refunded_units: 1 refunded_orders: 1 variations_omitted: 0 unknown: units: 0 orders: 0 refunded_units: 0 refunded_orders: 0 listings_omitted: 0 coverage: lines: 2 known: 2 unknown: 0 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. '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/variations?period=90d" \ -H "Authorization: Bearer $ALURA_API_KEY" - lang: typescript label: TypeScript source: >- const res = await fetch('https://api.alura.io/v1/workspace/stats/variations?period=90d', { 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/variations?period=90d", 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 - listing_not_publishable - sales_window_not_covered - unauthorized - credits_exhausted - plan_required - insufficient_scope - workspace_required - workspace_locked - your_shop_unavailable - writes_suspended - browser_refused - role_required - impersonation_refused - recent_sign_in_required - etsy_scope_required - etsy_partner_required - not_found - not_collected - not_found_on_etsy - shop_opted_out - method_not_allowed - conflict - key_limit_reached - reconnect_required - settings_not_fetched - listing_busy - settings_busy - shop_create_busy - idempotency_partial_unverifiable - listing_has_variations - listing_sold_out - changed_since - change_not_revertable - media_changed - listing_in_ab_test - activation_skipped - idempotency_processing - confirmation_required - test_shop_active_cap - write_outcome_unknown - unprocessable - listing_removed_on_etsy - endpoint_removed - rate_limited - throttled - daily_credit_cap_exceeded - credits_reserved - fetch_limit_reached - write_rate_limited - sync_cooldown - shop_write_budget_exhausted - internal_error - write_misconfigured - upstream_unavailable - credits_unavailable - service_unavailable - fetch_unavailable - create_lock_unavailable - writes_paused - 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.