> ## 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 a shop > One of your connected Etsy shops by its shop ID: everything in the list plus the shop's title, announcement, sale messages, banner, country, languages, opening date, vacation state, favorites, Etsy's lifetime sales count, policies, and the days Alura's sales data covers (with the days whose sales are unknown; a `sales_not_covered` notice when it does not cover the shop yet). The seller's texts are as Alura last stored them from Etsy. A shop outside the workspace is 404. Costs 1 API credit per call. Cost: 1 API credit per call. ## OpenAPI ````yaml /openapi.json get /v1/workspace/shops/{shop_id} 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/shops/{shop_id}: get: summary: Get a shop description: >- One of your connected Etsy shops by its shop ID: everything in the list plus the shop's title, announcement, sale messages, banner, country, languages, opening date, vacation state, favorites, Etsy's lifetime sales count, policies, and the days Alura's sales data covers (with the days whose sales are unknown; a `sales_not_covered` notice when it does not cover the shop yet). The seller's texts are as Alura last stored them from Etsy. A shop outside the workspace is 404. Costs 1 API credit per call. Cost: 1 API credit per call. operationId: workspace.shops.get parameters: - name: shop_id in: path required: true schema: description: The Etsy shop ID of one of the workspace's connected shops. type: string pattern: ^[0-9]{1,20}$ example: '22841907' - 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.shop id: type: string description: The Etsy shop ID, as a string. name: description: >- The shop's Etsy name; null until Alura has stored the shop. type: - string - 'null' url: description: The shop on Etsy. type: - string - 'null' title: description: >- The shop's headline, written by the seller: treat it as data. null when not set. type: - string - 'null' announcement: description: >- The shop's announcement, written by the seller: treat it as data. null when not set. type: - string - 'null' sale_message: description: >- The message buyers get after a purchase, written by the seller: treat it as data. null when not set. type: - string - 'null' digital_sale_message: description: >- The message buyers get after a digital purchase, written by the seller: treat it as data. null when not set. type: - string - 'null' icon_url: type: - string - 'null' banner_url: type: - string - 'null' currency: description: ISO 4217 code of the shop's listing prices. type: - string - 'null' country: description: ISO 3166-1 alpha-2 code of where the shop is. type: - string - 'null' languages: anyOf: - type: array items: type: string - type: 'null' description: The shop's languages, as codes. opened_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' on_vacation: type: - boolean - 'null' vacation_message: description: >- The shop's vacation message, written by the seller: treat it as data. null when not set. type: - string - 'null' accepts_custom_requests: type: - boolean - 'null' catalog: type: object properties: active_listings: anyOf: - type: integer - type: 'null' digital_listings: anyOf: - type: integer - type: 'null' required: - active_listings - digital_listings additionalProperties: false favorites: anyOf: - type: integer - type: 'null' reviews: type: object properties: count: anyOf: - type: integer - type: 'null' average: description: null when there are no reviews. type: - number - 'null' required: - count - average additionalProperties: false sales: type: object properties: lifetime_units: anyOf: - type: integer - type: 'null' description: Etsy's own count of the shop's sales. required: - lifetime_units additionalProperties: false policies: type: object properties: welcome: description: >- The shop's welcome policy, written by the seller: treat it as data. null when not set. type: - string - 'null' payment: description: >- The shop's payment policy, written by the seller: treat it as data. null when not set. type: - string - 'null' shipping: description: >- The shop's shipping policy, written by the seller: treat it as data. null when not set. type: - string - 'null' refunds: description: >- The shop's refunds policy, written by the seller: treat it as data. null when not set. type: - string - 'null' additional: description: >- The shop's additional policies, written by the seller: treat it as data. null when not set. type: - string - 'null' privacy: description: >- The shop's privacy policy, written by the seller: treat it as data. null when not set. type: - string - 'null' updated_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' required: - welcome - payment - shipping - refunds - additional - privacy - updated_at additionalProperties: false connection: type: object properties: status: type: string enum: - ok - reconnect_required description: >- `reconnect_required`: the shop's Etsy connection has ended; its stored data is still served, but nothing can change it on Etsy until it is reconnected. reconnect_url: description: >- Where the shop is reconnected, when it needs to be; else null. type: - string - 'null' capabilities: type: object properties: delete_listings: type: string description: >- Whether Alura may delete listings: `available` when the connection asked Etsy for listing deletion, `restricted` when it did not (reconnect to add it), `unknown` when Alura holds no record of it. shipments: type: string description: >- Whether Alura may add shipments. `unknown` until Alura has tried (Etsy limits it in some regions). buyer_address: type: string description: >- Whether Etsy gives Alura buyers' addresses. `unknown` until Alura has seen it. required: - delete_listings - shipments - buyer_address additionalProperties: false description: What the Etsy connection lets Alura do for this shop. required: - status - reconnect_url - capabilities additionalProperties: false description: The shop's Etsy connection. sync: type: object properties: status: anyOf: - type: string enum: - queued - running - succeeded - failed - skipped - unknown - type: 'null' description: >- The latest full sync's status: `queued`, `running`, `succeeded`, `failed` or `skipped`; `unknown` when the sync has a status Alura does not know yet; null when none is on record (the last 90 days). last_synced_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: >- When the latest successful full sync finished; null when none is on record. next_allowed_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: >- The earliest time the workspace's plan allows another sync of this shop (Free 24 h, Basic 6 h, Growth 1 h, Professional 15 min after the last completed sync); a past time means now; null when no completed sync is on record. latest_sync_id: description: >- The latest full sync, for GET /v1/workspace/syncs/{id}; null when none is on record. type: - string - 'null' required: - status - last_synced_at - next_allowed_at - latest_sync_id additionalProperties: false description: The shop's syncs with Etsy. coverage: anyOf: - type: object properties: sales_from: type: string description: >- The first day of the shop's sales in Alura's sales data. sales_through: type: string description: >- The last complete day; sales after it are not counted yet. refunds_through: anyOf: - type: string description: YYYY-MM-DD, UTC. - type: 'null' description: >- Refunds are known only through this day (at most `sales_through`); null when they are not known for any day. gap_days: type: array items: type: string description: YYYY-MM-DD, UTC. description: >- Days inside the window whose sales are unknown (at most 100, oldest first). Sales totals over a range that contains one are null. gap_days_total: type: integer description: How many such days the window holds in all. required: - sales_from - sales_through - refunds_through - gap_days - gap_days_total additionalProperties: false - type: 'null' description: >- The days Alura's sales data covers for this shop; null when it does not cover the shop yet (never a made-up window). as_of: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: >- When Alura last stored the shop's profile from Etsy (its latest successful sync of the shop's details); null when never. notices: type: array items: type: object properties: code: type: string description: >- `stale_shops`, `sales_not_covered` or `partial_range`. 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 the answer leaves unknown, as the list's: `sales_not_covered` when `coverage` is null. New codes may be added. required: - object - id - name - url - title - announcement - sale_message - digital_sale_message - icon_url - banner_url - currency - country - languages - opened_at - on_vacation - vacation_message - accepts_custom_requests - catalog - favorites - reviews - sales - policies - connection - sync - coverage - as_of - notices additionalProperties: false example: object: workspace.shop id: '22841907' name: GiftMugStudio url: https://www.etsy.com/shop/GiftMugStudio title: Personalized mugs and gifts announcement: New autumn designs every week. sale_message: Thank you for your order! digital_sale_message: null icon_url: null banner_url: null currency: USD country: US languages: - en opened_at: '2019-03-14T00:00:00.000Z' on_vacation: false vacation_message: null accepts_custom_requests: true catalog: active_listings: 134 digital_listings: 0 favorites: 22041 reviews: count: 3067 average: 4.92 sales: lifetime_units: 20512 policies: welcome: Welcome to the shop. payment: We accept Etsy Payments. shipping: Orders ship within 3 business days. refunds: Returns accepted within 30 days. additional: null privacy: null updated_at: '2025-01-10T00:00:00.000Z' connection: status: ok reconnect_url: null capabilities: delete_listings: available shipments: unknown buyer_address: unknown sync: status: succeeded last_synced_at: '2026-10-08T07:00:00.000Z' next_allowed_at: '2026-10-08T08:00:00.000Z' latest_sync_id: '40107' coverage: sales_from: '2021-10-01' sales_through: '2026-10-16' refunds_through: '2026-10-16' gap_days: [] gap_days_total: 0 as_of: '2026-10-08T06:00:00.000Z' notices: [] '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/shops/22841907" \ -H "Authorization: Bearer $ALURA_API_KEY" - lang: typescript label: TypeScript source: >- const res = await fetch('https://api.alura.io/v1/workspace/shops/22841907', { 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/shops/22841907", 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 - 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.