curl "https://api.alura.io/v1/workspace/customers/4242" \
-H "Authorization: Bearer $ALURA_API_KEY"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());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)){
"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"
}{
"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"
}{
"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"
}{
"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"
}{
"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"
}{
"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"
}{
"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"
}{
"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"
}{
"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"
}{
"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"
}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.
curl "https://api.alura.io/v1/workspace/customers/4242" \
-H "Authorization: Bearer $ALURA_API_KEY"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());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)){
"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"
}{
"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"
}{
"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"
}{
"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"
}{
"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"
}{
"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"
}{
"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"
}{
"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"
}{
"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"
}{
"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"
}Authorizations
An API key: Authorization: Bearer alura_sk_....
Path Parameters
The Etsy buyer's user ID. A buyer with no customer record in the workspace's shops is 404.
^[0-9]{1,20}$"4242"
Query Parameters
Comma-separated dotted paths to return; id, object and as_of always come back.
Response
OK
"workspace.customer"The Etsy buyer's user ID.
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.
Etsy ID, as a string.
The customer's name as stored on the customer row of the shop they ordered from last.
The buyer's Etsy profile image (75px); null when Alura has not stored it.
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.
Show child attributes
Show child attributes
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.
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.
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.
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.
Whether orders is 2 or more; null when orders is.
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.
Show child attributes
Show child attributes
lifetime_value divided by orders (recomputed from the sums, never averaged); null when either is.
Show child attributes
Show child attributes
Refunds to the customer.
Show child attributes
Show child attributes
Reviews the customer left the selected shops.
Show child attributes
Show child attributes
When the customer was last computed: the oldest customers step of the customer's shops; null when one of them was never computed.