> ## 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. # Search customers > Lists the customers (Etsy buyers) of your connected Etsy shops: filter repeat customers (`repeat`) and by when they ordered (`ordered_after`, `ordered_before`); sort by lifetime value, orders, last order or first order, most recent last order first by default. The lifetime value sort ranks by the total Alura stored for each customer (in USD): a customer whose total Alura cannot verify against the stored orders keeps that rank with `lifetime_value: null`, and a `lifetime_value_ranked_by_stored_total` notice says so; customers with no stored total come last. 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=`. A shop whose customers Alura has not computed yet is left out and named in a `customers_not_computed` notice. Covers every connected shop unless `shop_id` narrows it; a shop outside the workspace is 404. `summary` gives each shop's data time and a `stale_shops` notice for shops not synced for 7 days. The results hold buyer names and cities (personal data, as Etsy provides it). To filter by name or country, use `POST /v1/workspace/customers/search` with them in the JSON body: this GET takes no free text, so buyer data never goes in a URL (URLs are kept in request logs). 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 page with results; an empty page is free. Cost: 1 API credit per page. ## OpenAPI ````yaml /openapi.json get /v1/workspace/customers 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: get: summary: Search customers description: >- Lists the customers (Etsy buyers) of your connected Etsy shops: filter repeat customers (`repeat`) and by when they ordered (`ordered_after`, `ordered_before`); sort by lifetime value, orders, last order or first order, most recent last order first by default. The lifetime value sort ranks by the total Alura stored for each customer (in USD): a customer whose total Alura cannot verify against the stored orders keeps that rank with `lifetime_value: null`, and a `lifetime_value_ranked_by_stored_total` notice says so; customers with no stored total come last. 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=`. A shop whose customers Alura has not computed yet is left out and named in a `customers_not_computed` notice. Covers every connected shop unless `shop_id` narrows it; a shop outside the workspace is 404. `summary` gives each shop's data time and a `stale_shops` notice for shops not synced for 7 days. The results hold buyer names and cities (personal data, as Etsy provides it). To filter by name or country, use `POST /v1/workspace/customers/search` with them in the JSON body: this GET takes no free text, so buyer data never goes in a URL (URLs are kept in request logs). 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 page with results; an empty page is free. Cost: 1 API credit per page. operationId: workspace.customers.search 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: ordered_after in: query required: false description: >- Only customers with an order at or after this time (a date is midnight UTC). schema: description: >- Only customers with an order at or after this time (a date is midnight UTC). type: string pattern: >- ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2}))?$ - name: ordered_before in: query required: false description: Only customers with an order before this time. schema: description: Only customers with an order before this time. type: string pattern: >- ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2}))?$ - name: sort in: query required: false description: >- `lifetime_value`, `orders`, `last_order`, `first_order`; prefix `-` for descending. Default `-last_order`. `lifetime_value` ranks by the lifetime total Alura stored for each customer, in USD at the request's exchange rates: a customer whose total Alura cannot verify against the stored orders keeps that rank with `lifetime_value: null` (the `lifetime_value_ranked_by_stored_total` notice says so), and customers with no stored total come last. `orders` ranks by the order count Alura stored for each customer, which may include canceled orders Etsy says were never paid (the served `orders` leaves those out). For the other sorts, customers whose value is unknown come last. Ties go by customer ID. schema: description: >- `lifetime_value`, `orders`, `last_order`, `first_order`; prefix `-` for descending. Default `-last_order`. `lifetime_value` ranks by the lifetime total Alura stored for each customer, in USD at the request's exchange rates: a customer whose total Alura cannot verify against the stored orders keeps that rank with `lifetime_value: null` (the `lifetime_value_ranked_by_stored_total` notice says so), and customers with no stored total come last. `orders` ranks by the order count Alura stored for each customer, which may include canceled orders Etsy says were never paid (the served `orders` leaves those out). For the other sorts, customers whose value is unknown come last. Ties go by customer ID. type: string enum: - lifetime_value - orders - last_order - first_order - '-lifetime_value' - '-orders' - '-last_order' - '-first_order' example: '-lifetime_value' - name: repeat in: query required: false description: >- true: only customers with 2 or more orders; false: only customers with one. By the order count Alura stored for each customer, which may include canceled orders Etsy says were never paid, so a customer's served `repeat` can differ. schema: description: >- true: only customers with 2 or more orders; false: only customers with one. By the order count Alura stored for each customer, which may include canceled orders Etsy says were never paid, so a customer's served `repeat` can differ. type: string enum: - 'true' - 'false' example: 'true' - name: limit in: query required: false description: 'Page size: default 25, at most 100.' schema: type: integer minimum: 1 maximum: 100 - name: cursor in: query required: false description: >- The `next_cursor` of the previous page. Bound to the query, the workspace and the key. schema: type: string - 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: list data: type: array items: 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 has_more: type: boolean next_cursor: type: - string - 'null' total: type: object properties: value: type: integer relation: type: string enum: - eq - gte required: - value - relation additionalProperties: false summary: type: object properties: 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 data time; null when a shop's is unknown. 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 description: Each included shop's data time. notices: type: array items: type: object properties: code: type: string description: >- `stale_shops`, `sales_not_covered`, `partial_range`, `settings_not_fetched`, `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`, `customers_not_computed`, `lifetime_value_ranked_by_stored_total`, `refunds_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 fx_as_of: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: >- When the exchange rates of the selected shops' currencies, which value the `usd` amounts, were last updated; null when none are stored. required: - as_of - freshness - notices - fx_as_of additionalProperties: false required: - object - data - has_more - next_cursor - total - summary additionalProperties: false example: object: list data: - 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' has_more: false next_cursor: null total: value: 1 relation: eq summary: 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. - code: lifetime_value_ranked_by_stored_total shop_ids: - '22841907' - '30577120' - '48911633' detail: >- Ranked by the lifetime total Alura stored for each customer. A customer whose total Alura cannot verify against the stored orders keeps that rank with lifetime_value null; customers with no stored total come last. fx_as_of: '2026-10-17T00: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?repeat=true&sort=-lifetime_value" \ -H "Authorization: Bearer $ALURA_API_KEY" - lang: typescript label: TypeScript source: >- const res = await fetch('https://api.alura.io/v1/workspace/customers?repeat=true&sort=-lifetime_value', { 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?repeat=true&sort=-lifetime_value", 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.