> ## 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 customer > One customer of your connected Etsy shops by their Etsy buyer ID: orders, items, first and last order, lifetime value, average order value, refunds and reviews. A buyer who ordered from several of your connected shops is one customer, summed over the selected shops (counts and amounts summed, the average order value recomputed, the review average weighted, the name and location from the shop ordered from last). Guest checkouts (no Etsy account) are not customers. An amount Alura cannot vouch for (a payment, item or refund it has not stored) is null, never a short total; amounts in several currencies give only `usd`. A customer's orders are `GET /v1/workspace/orders?buyer_id=`. When the customer also ordered from a connected shop whose customers Alura has not computed yet, the merged numbers (orders, items, first and last order, repeat, lifetime value, average order value, refunds and reviews) are null, never a short total; the name and location come from the computed shops, and `shop_ids` lists every connected shop they ordered from, that one included. A buyer with no customer record in your shops (another workspace's buyer, a guest, or one whose shop's customers are not computed yet) is 404. Holds buyer personal data, as Etsy provides it. A large workspace may take up to 10 seconds: every customer of the selected shops is merged before sorting; past that, a retryable 503. Needs the `customers:read` scope and the Customer analytics workspace permission. Costs 1 API credit per call. Cost: 1 API credit per call. ## OpenAPI ````yaml /openapi.json get /v1/workspace/customers/{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/customers/{id}: get: summary: Get a customer description: >- One customer of your connected Etsy shops by their Etsy buyer ID: orders, items, first and last order, lifetime value, average order value, refunds and reviews. A buyer who ordered from several of your connected shops is one customer, summed over the selected shops (counts and amounts summed, the average order value recomputed, the review average weighted, the name and location from the shop ordered from last). Guest checkouts (no Etsy account) are not customers. An amount Alura cannot vouch for (a payment, item or refund it has not stored) is null, never a short total; amounts in several currencies give only `usd`. A customer's orders are `GET /v1/workspace/orders?buyer_id=`. When the customer also ordered from a connected shop whose customers Alura has not computed yet, the merged numbers (orders, items, first and last order, repeat, lifetime value, average order value, refunds and reviews) are null, never a short total; the name and location come from the computed shops, and `shop_ids` lists every connected shop they ordered from, that one included. A buyer with no customer record in your shops (another workspace's buyer, a guest, or one whose shop's customers are not computed yet) is 404. Holds buyer personal data, as Etsy provides it. A large workspace may take up to 10 seconds: every customer of the selected shops is merged before sorting; past that, a retryable 503. Needs the `customers:read` scope and the Customer analytics workspace permission. Costs 1 API credit per call. Cost: 1 API credit per call. operationId: workspace.customers.get parameters: - name: id in: path required: true schema: description: >- The Etsy buyer's user ID. A buyer with no customer record in the workspace's shops is 404. type: string pattern: ^[0-9]{1,20}$ example: '4242' - 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.customer id: type: string description: The Etsy buyer's user ID. shop_ids: type: array items: type: string description: Etsy ID, as a string. description: >- The selected connected shops the customer ordered from (ascending). For one customer by ID whose merged numbers are null because they ordered from a connected shop whose customers step has not run yet, every connected shop they ordered from, that one included. name: description: >- The customer's name as stored on the customer row of the shop they ordered from last. type: - string - 'null' image_url: description: >- The buyer's Etsy profile image (75px); null when Alura has not stored it. type: - string - 'null' location: type: object properties: country: description: >- ISO 3166-1 alpha-2 country code, as stored on the customer row of the shop they ordered from last. type: - string - 'null' city: type: - string - 'null' required: - country - city additionalProperties: false description: >- Where the customer's orders ship, as stored on the customer row of the shop they ordered from last (that row keeps one ship-to per shop, not necessarily the latest order's); a part Etsy did not give is null. orders: anyOf: - type: integer - type: 'null' description: >- Orders placed, summed over the selected shops. A canceled order Etsy says was never paid is not an order: left out once Alura has stored every one of the customer's orders in a shop; until then, that shop's count is the stored count, which may include one. null when a shop's count is unknown, or, for one customer by ID, when they ordered from a connected shop whose customers step has not run yet. items: anyOf: - type: integer - type: 'null' description: >- Units ordered, summed; null when Alura has not stored every order's items, or, for one customer by ID, when they ordered from a connected shop whose customers step has not run yet. first_order_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: >- The customer's first order in the selected shops, ISO 8601, UTC; null when unknown, or, for one customer by ID, when they ordered from a connected shop whose customers step has not run yet. last_order_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: >- The customer's latest order in the selected shops, ISO 8601, UTC; null when unknown, or, for one customer by ID, when they ordered from a connected shop whose customers step has not run yet. repeat: description: Whether `orders` is 2 or more; null when `orders` is. type: - boolean - 'null' lifetime_value: anyOf: - type: object properties: amount: description: >- Decimal string in `currency`; null when the shops it sums are in different currencies. type: - string - 'null' currency: description: ISO 4217 code of the shops; null when they differ. type: - string - 'null' usd: description: >- The total in USD at the request's exchange rates (`summary.fx_as_of`), as a decimal string; null when a rate is unknown. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: >- A sum over the customer's orders in the selected shops; null when Alura cannot vouch for it. - type: 'null' description: >- What the customer paid, summed over the selected shops (Etsy's payment gross). null when Alura has not stored every payment, or, for one customer by ID, when they ordered from a connected shop whose customers step has not run yet, so a total is never short. average_order_value: anyOf: - type: object properties: amount: description: >- Decimal string in `currency`; null when the shops it sums are in different currencies. type: - string - 'null' currency: description: ISO 4217 code of the shops; null when they differ. type: - string - 'null' usd: description: >- The total in USD at the request's exchange rates (`summary.fx_as_of`), as a decimal string; null when a rate is unknown. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: >- A sum over the customer's orders in the selected shops; null when Alura cannot vouch for it. - type: 'null' description: >- `lifetime_value` divided by `orders` (recomputed from the sums, never averaged); null when either is. refunds: type: object properties: count: anyOf: - type: integer - type: 'null' description: >- Orders with at least one Etsy refund record (whatever the order's status: most refunded orders are canceled ones), summed over the selected shops. null, with `amount`, when Alura cannot vouch for every refund: an order is not stored, or an order Etsy may have refunded (refunded, or canceled and paid) has no refund record stored (a `refunds_unknown` notice says so), or, for one customer by ID, when they ordered from a connected shop whose customers step has not run yet. amount: anyOf: - type: object properties: amount: description: >- Decimal string in `currency`; null when the shops it sums are in different currencies. type: - string - 'null' currency: description: >- ISO 4217 code of the shops; null when they differ. type: - string - 'null' usd: description: >- The total in USD at the request's exchange rates (`summary.fx_as_of`), as a decimal string; null when a rate is unknown. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: >- A sum over the customer's orders in the selected shops; null when Alura cannot vouch for it. - type: 'null' description: >- What was refunded: the sum of the same orders' Etsy refund records; null when `count` is. required: - count - amount additionalProperties: false description: Refunds to the customer. reviews: type: object properties: count: anyOf: - type: integer - type: 'null' description: >- Reviews the customer left, summed; null when unknown, as while a selected shop's reviews were never synced (`reviews_not_synced`), or, for one customer by ID, when they ordered from a connected shop whose customers step has not run yet; never a made-up 0. average: description: >- Their average rating, weighted by each shop's count; null with no review. type: - number - 'null' required: - count - average additionalProperties: false description: Reviews the customer left the selected shops. as_of: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: >- When the customer was last computed: the oldest customers step of the customer's shops; null when one of them was never computed. required: - object - id - shop_ids - name - image_url - location - orders - items - first_order_at - last_order_at - repeat - lifetime_value - average_order_value - refunds - reviews - as_of additionalProperties: false example: object: workspace.customer id: '4242' shop_ids: - '22841907' - '30577120' name: Jane Example image_url: null location: country: US city: Portland orders: 4 items: 5 first_order_at: '2025-11-02T15:20:00.000Z' last_order_at: '2026-10-05T18:45:00.000Z' repeat: true lifetime_value: amount: '138.40' currency: USD usd: '138.40' average_order_value: amount: '34.60' currency: USD usd: '34.60' refunds: count: 1 amount: amount: '12.00' currency: USD usd: '12.00' reviews: count: 3 average: 4.67 as_of: '2026-10-08T06:00:00.000Z' '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/customers/4242" \ -H "Authorization: Bearer $ALURA_API_KEY" - lang: typescript label: TypeScript source: >- const res = await fetch('https://api.alura.io/v1/workspace/customers/4242', { 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/customers/4242", 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.