Browse developer documentation
Reports
Who is buying
See paying customers grouped into the dashboard's five customer types, each customer's source and credited source, visitors who almost bought, and companies and cities.
GET
/api/v1/stats/buyersAccess: Workspace key or OAuth analytics:read · Permission details
Query parameters
| Field | Type | Description |
|---|---|---|
site | string | Website ID or domain. Required when the workspace has more than one website. |
period | string | Saved website timezone calendar selection. from and to override period. Values: realtime, today, yesterday, 7d, 30d, 90d, 12m, wtd, mtd, qtd, ytd, all. Default: |
from | string | Inclusive website-local start date. Supply to as well. |
to | string | Inclusive website-local end date. Supply from as well. |
compare | string | Comparison range. Values: previous_period, mom, qoq, yoy, none. Default: |
model | string | Which visit gets credit for a sale, the same six rules as the dashboard's Credit menu. Values: first_touch, last_touch, last_non_direct, u_shaped, linear, time_decay. Default: |
lookback | string | How far back before each sale visits can get credit. Older visits get no credit; if none fall inside the window, the latest recorded visit keeps it. Larger-site database reports, visitor filters and cursors only accept all. Values: all, 90d, 30d, 7d. Default: |
filters | string | URL-encoded JSON array of up to twenty visitor filters, for example [{"dim":"country","op":"is","value":"US"}]. Dimensions: source, channel, campaign, entry_page, page, hostname, country, device, browser, os, goal. Operators: is, is_not. Values are exact strings up to 500 characters. All filters must match the visitor across available history; report dates then select activity for that cohort. Unmatched payments are excluded. Crawler counts remain website-wide; spend requires every filter to be source/channel/campaign. Preserve filters when paging. |
limit | integer | Row limit for reports that support it. Default: |
customer | string | A customer id, visitor_id or email from customers. Returns that customer's full history instead of the lists. |
Request examples
Examples run from your server or terminal. Configure ATTRIBOO_TOKEN privately for authenticated requests. Replace example website IDs and values with your own. The examples make real requests when you run them.
cURL request
curl "https://www.attriboo.com/api/v1/stats/buyers?site=site_example&from=2026-10-01&to=2026-10-07&compare=none" \
-H "Authorization: Bearer $ATTRIBOO_TOKEN"Response
Illustrative response. Fields below are inside the data object. Optional coverage, notes and continuation fields vary by report.
| Field | Type | Description |
|---|---|---|
site | object | Website ID, domain and currency. |
period | object | Website-calendar boundaries returned as UTC timestamps; to is exclusive. |
summary | object | customers, paid, refunded, orders, repeat_customers, repeat_customer_rate_pct, average_order, average_visits_to_buy, average_time_to_buy_seconds and almost_buying. |
customer_types | array | The five customer types in the dashboard's order. |
customers | array | Customers who paid in the selected dates, highest spend first. |
almost_buying | array | Visitors with buying signals and no payment: visitor_id, label, email, city, country, visits, pageviews, found_via, last_page, goals, reason, last_seen_at. |
companies | array | name, domain, account_type, customers, orders, paid, lifetime, share_of_sales_pct, top_source. Personal email addresses are grouped by city. |
cities | array | city, country, customers, orders, paid, share_of_sales_pct, top_source. |
customer | object | Returned instead of the lists when customer= is set: the customer fields plus history. |
notes | string | How to read the amounts and types. |
site fields
| Field | Type | Description |
|---|---|---|
id | string | Website ID. |
domain | string | Website domain. |
currency | string | Three-letter currency. |
period fields
| Field | Type | Description |
|---|---|---|
from | string | Inclusive UTC start. |
to | string | Exclusive UTC end. |
label | string | Human-readable date selection. |
timezone | string | Saved IANA website timezone used to resolve calendar dates. |
compare | string | Comparison selection. |
attribution_model | string | Revenue-credit model. |
lookback | string | Look-back window used for revenue credit. Small-site reports return it; larger-site database reports always use every visit. |
customer_types[] fields
| Field | Type | Description |
|---|---|---|
type | string | repeat_high_value, found_through_ai, took_several_visits, came_from_an_ad or bought_on_first_visit. |
label | string | Dashboard label. |
description | string | What puts a customer in this type. |
customers | integer | Customers. |
orders | integer | Orders. |
paid | integer | Paid in the selected dates, cents. |
share_of_sales_pct | number | Percentage of selected-date sales. |
share_of_customers_pct | number | Percentage of customers. |
top_source | string | null | Leading credited source or null. |
customers[] fields
| Field | Type | Description |
|---|---|---|
id | string | Customer ID for customer=. |
visitor_id | string | null | Tracked visitor ID or null. |
name | string | Customer name, or a placeholder when none was recorded. |
email | string | null | Email or null. |
company | string | null | Company from a business email domain, or null. |
city | string | null | City or null. |
country | string | null | Country or null. |
type | string | Customer type. |
status | string | repeat, subscriber, first_purchase, cancelled or refunded. |
found_via | string | Source of the first recorded visit. |
credited_to | string | Source credited under model and lookback. |
paid | integer | Paid in the selected dates after refunds, cents. |
refunded | integer | Refunded cents. |
lifetime | integer | Every recorded payment, cents. |
orders | integer | Orders. |
renewals | integer | Subscription renewals. |
visits_before_buying | integer | Recorded visits before paying. |
time_to_buy_seconds | integer | Seconds from first visit to purchase. |
first_seen_at | string | null | First recorded visit or null. |
last_purchase_at | string | null | Latest purchase or null. |
self_reported_source | string | null | Checkout poll answer or null. |
credit_split | array | Visits that got credit: source, channel, landing_page, visited_at, campaign, credit (cents), credit_pct. |
JSON response
{
"status": "success",
"data": {
"site": {
"id": "site_example",
"domain": "shop.example.com",
"currency": "USD"
},
"period": {
"from": "2026-10-01T00:00:00.000Z",
"to": "2026-10-08T00:00:00.000Z",
"label": "Custom",
"timezone": "UTC",
"compare": "none",
"attribution_model": "first_touch",
"lookback": "all"
},
"summary": {
"customers": 1,
"paid": 19900,
"refunded": 0,
"orders": 1,
"repeat_customers": 0,
"repeat_customer_rate_pct": 0,
"average_order": 19900,
"average_visits_to_buy": 2,
"average_time_to_buy_seconds": 86400,
"almost_buying": 1
},
"customer_types": [
{
"type": "repeat_high_value",
"label": "Repeat & high value",
"description": "Bought more than once, renewed a subscription, or has paid well above the website's average order.",
"customers": 0,
"orders": 0,
"paid": 0,
"share_of_sales_pct": 0,
"share_of_customers_pct": 0,
"top_source": null
},
{
"type": "found_through_ai",
"label": "Found you through AI",
"description": "Visited from ChatGPT, Perplexity, Claude, Gemini or Copilot before paying, or named an AI assistant in the checkout poll.",
"customers": 1,
"orders": 1,
"paid": 19900,
"share_of_sales_pct": 100,
"share_of_customers_pct": 100,
"top_source": "ChatGPT"
}
],
"customers": [
{
"id": "buyer_1",
"visitor_id": "v_1",
"name": "Alex Example",
"email": "alex@example.com",
"company": "Example Co",
"city": "Austin",
"country": "United States",
"type": "found_through_ai",
"status": "first_purchase",
"found_via": "ChatGPT",
"credited_to": "ChatGPT",
"paid": 19900,
"refunded": 0,
"lifetime": 19900,
"orders": 1,
"renewals": 0,
"visits_before_buying": 2,
"time_to_buy_seconds": 86400,
"first_seen_at": "2026-10-02T10:00:00.000Z",
"last_purchase_at": "2026-10-03T10:00:00.000Z",
"self_reported_source": null,
"credit_split": [
{
"source": "ChatGPT",
"channel": "AI Referral",
"landing_page": "/pricing",
"visited_at": "2026-10-02T10:00:00.000Z",
"campaign": null,
"credit": 19900,
"credit_pct": 100
}
]
}
],
"almost_buying": [
{
"visitor_id": "v_2",
"label": "Visitor in Austin",
"email": null,
"city": "Austin",
"country": "United States",
"visits": 3,
"pageviews": 7,
"found_via": "Google Organic",
"last_page": "/pricing",
"goals": [],
"reason": "Viewed /pricing across 3 sessions from Google Organic.",
"last_seen_at": "2026-10-06T10:00:00.000Z"
}
],
"companies": [
{
"name": "Example Co",
"domain": "example.com",
"account_type": "business",
"customers": 1,
"orders": 1,
"paid": 19900,
"lifetime": 19900,
"share_of_sales_pct": 100,
"top_source": "ChatGPT"
}
],
"cities": [
{
"city": "Austin",
"country": "United States",
"customers": 1,
"orders": 1,
"paid": 19900,
"share_of_sales_pct": 100,
"top_source": "ChatGPT"
}
],
"notes": "Money is in integer cents."
}
}Behavior and limits
Money is integer cents in site.currency. Percentages use a 0–100 scale.
Matches the dashboard's Buyers tab and its Credit setting. A customer belongs to the first type that fits, in the order listed.
Available for websites on the standard report view. Larger-site database reports and visitor filters return HTTP 400; use sales for payment-level attribution there.
limit caps each list. almost_buying holds up to 20 visitors with buying signals (pricing, comparison or checkout pages, sign-up or checkout goals, an email, or repeat visits) and no payment.
customer=ID, visitor ID or email returns that customer with history: kind (visit, page, goal, purchase, refund), at, title, detail, source, page, campaign, amount, credit, credit_pct and self_reported_source.