Customers

New vs returning customers

GET https://thoughtmetric.io/api/v1/new_returning_customer_data

Splits orders, sales and refunds between customers buying for the first time and customers who have bought before.

Example request

curl -G https://thoughtmetric.io/api/v1/new_returning_customer_data \
  -H "Authorization: Bearer 2019962dcf7a7b1fedc4563b9aaf9fc87426f278" \
  -d projectId=ID-bcd0aa692ce7e6b2 \
  -d startDate=2024-01-01 \
  -d endDate=2024-01-31 \
  -d interval=day

<?php

$query = http_build_query([
    'projectId' => 'ID-bcd0aa692ce7e6b2',
    'startDate' => '2024-01-01',
    'endDate'   => '2024-01-31',
    'interval'  => 'day',
]);

$ch = curl_init('https://thoughtmetric.io/api/v1/new_returning_customer_data?' . $query);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer 2019962dcf7a7b1fedc4563b9aaf9fc87426f278',
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

const params = new URLSearchParams({
  projectId: 'ID-bcd0aa692ce7e6b2',
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  interval: 'day',
});

const response = await fetch(
  `https://thoughtmetric.io/api/v1/new_returning_customer_data?${params}`,
  { headers: { Authorization: 'Bearer 2019962dcf7a7b1fedc4563b9aaf9fc87426f278' } }
);

const data = await response.json();

Query parameters

projectId string, required	The Project ID of the store you are querying, e.g. ID-bcd0aa692ce7e6b2. Find it under Configure → API in the dashboard. The older numeric project ID is also accepted.
startDate string, required	Start of the reporting window, YYYY-MM-DD. Inclusive.
endDate string, required	End of the reporting window, YYYY-MM-DD. Inclusive. The window may not exceed six months.
interval string, required	Bucket size for the over_time series: day, week, month or year.

Response

total object

Totals for the whole reporting window.

new_customer_orders number	Orders placed by first-time customers.
new_customers number	Duplicate of new_customer_orders, kept for backwards compatibility.
new_customer_total_sales number	Sales from first-time customers.
new_customer_total_refund number	Refunds issued to first-time customers.
returning_customer_orders number	Orders placed by returning customers.
returning_customer_total_sales number	Sales from returning customers.
returning_customer_total_refund number	Refunds issued to returning customers.

over_time array

One object per interval bucket, oldest first. Same metrics as total, plus time. Buckets with no activity come back as zeroes.

time string

Start of the interval bucket, as an ISO 8601 timestamp.

Example response

200 OK

{
  "total": {
    "new_customer_orders": 902.0,
    "new_customers": 902.0,
    "new_customer_total_sales": 99420.10,
    "new_customer_total_refund": 2100.00,
    "returning_customer_orders": 382.0,
    "returning_customer_total_sales": 42685.34,
    "returning_customer_total_refund": 1020.00
  },
  "over_time": [
    {
      "time": "2024-01-01T00:00:00.000Z",
      "new_customer_orders": 29.0,
      "new_customers": 29.0,
      "new_customer_total_sales": 3180.44,
      "new_customer_total_refund": 0.0,
      "returning_customer_orders": 12.0,
      "returning_customer_total_sales": 1349.74,
      "returning_customer_total_refund": 0.0
    }
  ]
}