> ## 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 by name or country > Searches the customers of your connected Etsy shops like `GET /v1/workspace/customers`, with every filter in the JSON body, plus `q` (a part of the customer's name, case-insensitive) and `country` (where their orders ship). A POST because a name and a location are personal data and URLs are kept in request logs: they stay in the body. It reads only; nothing changes. `cursor` and `limit` go in the query string. 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 post /v1/workspace/customers/search 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/search: post: summary: Search customers by name or country description: >- Searches the customers of your connected Etsy shops like `GET /v1/workspace/customers`, with every filter in the JSON body, plus `q` (a part of the customer's name, case-insensitive) and `country` (where their orders ship). A POST because a name and a location are personal data and URLs are kept in request logs: they stay in the body. It reads only; nothing changes. `cursor` and `limit` go in the query string. 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.query parameters: - 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 requestBody: required: false content: application/json: schema: type: object properties: shop_id: 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 ordered_after: 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}))?$ ordered_before: 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}))?$ sort: 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' repeat: 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: boolean country: description: >- Only customers whose orders ship to this country (ISO 3166-1 alpha-2), 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, so a customer whose ship-to changed can be missed. type: string pattern: ^[A-Za-z]{2}$ q: description: >- A part of the customer's name (case-insensitive), as any of the selected shops stores it. type: string additionalProperties: false example: q: Jane 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. 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 -X POST "https://api.alura.io/v1/workspace/customers/search" \ -H "Authorization: Bearer $ALURA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"q":"Jane"}' - lang: typescript label: TypeScript source: >- const res = await fetch('https://api.alura.io/v1/workspace/customers/search', { method: 'POST', headers: { Authorization: `Bearer ${process.env.ALURA_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "q": "Jane" }), }); 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/search", method="POST", data=json.dumps({ "q": "Jane" }).encode(), headers={ "Authorization": f"Bearer {os.environ['ALURA_API_KEY']}", "Content-Type": "application/json", }, ) 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.