Customers

New vs returning by channel

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

The same first-time versus returning breakdown, split by the marketing channel each order is attributed to. Useful for spotting which channels bring in genuinely new customers.

Example request

curl -G https://thoughtmetric.io/api/v1/new_returning_customer_data_by_channel \
  -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_by_channel?' . $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_by_channel?${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.
model string, optional	Attribution model: first, last, position, linearNonDirect or linearPaid. Defaults to the model configured on the project.

Response

total array

One object per channel, covering the whole reporting window.

channel number	Marketing channel the row is attributed to, e.g. facebookad, googlead, organic, direct.
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 channel per interval bucket, ordered by time then channel.

time string

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

Example response

200 OK

{
  "total": [
    {
      "channel": "facebookad",
      "new_customer_orders": 402.0,
      "new_customers": 402.0,
      "new_customer_total_sales": 44210.80,
      "new_customer_total_refund": 900.00,
      "returning_customer_orders": 110.0,
      "returning_customer_total_sales": 13999.64,
      "returning_customer_total_refund": 220.00
    }
  ],
  "over_time": [
    {
      "time": "2024-01-01T00:00:00.000Z",
      "channel": "facebookad",
      "new_customer_orders": 13.0,
      "new_customers": 13.0,
      "new_customer_total_sales": 1450.20,
      "new_customer_total_refund": 0.0,
      "returning_customer_orders": 4.0,
      "returning_customer_total_sales": 452.35,
      "returning_customer_total_refund": 0.0
    }
  ]
}