Browse developer documentation
Read-only tool
get_buyers
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.
Access: OAuth analytics:read or a privately configured workspace key.
Arguments
| Field | Type | Description |
|---|---|---|
compare | string | Comparison range. Values: previous_period, mom, qoq, yoy, none. Default: |
customer | string | A customer id, visitor_id or email from customers. Returns that customer's full history instead of the lists. |
filters | array | 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. |
from | string | Inclusive website-local start date. Supply to as well. |
limit | integer | Maximum rows on this page. 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: |
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: |
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: |
site | string | Website ID or domain. Required when the workspace has more than one website. |
to | string | Inclusive website-local end date. Supply from as well. |
filters[] fields
| Field | Type | Description |
|---|---|---|
dim | string | Values: source, channel, campaign, entry_page, page, hostname, country, device, browser, os, goal. |
op | string | Values: is, is_not. |
value | string |
Read who is buying
Use this JSON-RPC call through an initialized MCP client. Replace example values with your actual website, dates or confirmed setup details.
MCP tools/call request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_buyers",
"arguments": {
"site": "site_example",
"from": "2026-10-01",
"to": "2026-10-07",
"compare": "none"
}
}
}Decoded result
Illustrative JSON parsed from the result’s text block.
Decoded JSON result
{
"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."
}Result fields
| 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. |
The decoded data follows the who is buying response contract, without the REST envelope.
Full MCP result wrapper
MCP result object
{
"content": [
{
"type": "text",
"text": "{\n \"site\": {\n \"id\": \"site_example\",\n \"domain\": \"shop.example.com\",\n \"currency\": \"USD\"\n },\n \"period\": {\n \"from\": \"2026-10-01T00:00:00.000Z\",\n \"to\": \"2026-10-08T00:00:00.000Z\",\n \"label\": \"Custom\",\n \"timezone\": \"UTC\",\n \"compare\": \"none\",\n \"attribution_model\": \"first_touch\",\n \"lookback\": \"all\"\n },\n \"summary\": {\n \"customers\": 1,\n \"paid\": 19900,\n \"refunded\": 0,\n \"orders\": 1,\n \"repeat_customers\": 0,\n \"repeat_customer_rate_pct\": 0,\n \"average_order\": 19900,\n \"average_visits_to_buy\": 2,\n \"average_time_to_buy_seconds\": 86400,\n \"almost_buying\": 1\n },\n \"customer_types\": [\n {\n \"type\": \"repeat_high_value\",\n \"label\": \"Repeat & high value\",\n \"description\": \"Bought more than once, renewed a subscription, or has paid well above the website's average order.\",\n \"customers\": 0,\n \"orders\": 0,\n \"paid\": 0,\n \"share_of_sales_pct\": 0,\n \"share_of_customers_pct\": 0,\n \"top_source\": null\n },\n {\n \"type\": \"found_through_ai\",\n \"label\": \"Found you through AI\",\n \"description\": \"Visited from ChatGPT, Perplexity, Claude, Gemini or Copilot before paying, or named an AI assistant in the checkout poll.\",\n \"customers\": 1,\n \"orders\": 1,\n \"paid\": 19900,\n \"share_of_sales_pct\": 100,\n \"share_of_customers_pct\": 100,\n \"top_source\": \"ChatGPT\"\n }\n ],\n \"customers\": [\n {\n \"id\": \"buyer_1\",\n \"visitor_id\": \"v_1\",\n \"name\": \"Alex Example\",\n \"email\": \"alex@example.com\",\n \"company\": \"Example Co\",\n \"city\": \"Austin\",\n \"country\": \"United States\",\n \"type\": \"found_through_ai\",\n \"status\": \"first_purchase\",\n \"found_via\": \"ChatGPT\",\n \"credited_to\": \"ChatGPT\",\n \"paid\": 19900,\n \"refunded\": 0,\n \"lifetime\": 19900,\n \"orders\": 1,\n \"renewals\": 0,\n \"visits_before_buying\": 2,\n \"time_to_buy_seconds\": 86400,\n \"first_seen_at\": \"2026-10-02T10:00:00.000Z\",\n \"last_purchase_at\": \"2026-10-03T10:00:00.000Z\",\n \"self_reported_source\": null,\n \"credit_split\": [\n {\n \"source\": \"ChatGPT\",\n \"channel\": \"AI Referral\",\n \"landing_page\": \"/pricing\",\n \"visited_at\": \"2026-10-02T10:00:00.000Z\",\n \"campaign\": null,\n \"credit\": 19900,\n \"credit_pct\": 100\n }\n ]\n }\n ],\n \"almost_buying\": [\n {\n \"visitor_id\": \"v_2\",\n \"label\": \"Visitor in Austin\",\n \"email\": null,\n \"city\": \"Austin\",\n \"country\": \"United States\",\n \"visits\": 3,\n \"pageviews\": 7,\n \"found_via\": \"Google Organic\",\n \"last_page\": \"/pricing\",\n \"goals\": [],\n \"reason\": \"Viewed /pricing across 3 sessions from Google Organic.\",\n \"last_seen_at\": \"2026-10-06T10:00:00.000Z\"\n }\n ],\n \"companies\": [\n {\n \"name\": \"Example Co\",\n \"domain\": \"example.com\",\n \"account_type\": \"business\",\n \"customers\": 1,\n \"orders\": 1,\n \"paid\": 19900,\n \"lifetime\": 19900,\n \"share_of_sales_pct\": 100,\n \"top_source\": \"ChatGPT\"\n }\n ],\n \"cities\": [\n {\n \"city\": \"Austin\",\n \"country\": \"United States\",\n \"customers\": 1,\n \"orders\": 1,\n \"paid\": 19900,\n \"share_of_sales_pct\": 100,\n \"top_source\": \"ChatGPT\"\n }\n ],\n \"notes\": \"Money is in integer cents.\"\n}"
}
]
}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.
Report tools return the report data directly inside MCP text content. They do not add the REST status/data envelope.
With multiple websites and no site argument, this report tool returns needs_site: true and the available websites. Choose a real website and call it again.