Working with Timestamps

The Katalys API returns and accepts timestamps as epoch-milliseconds. An epoch is a computing value that represents a date+time as seconds or milliseconds from 1970-01-01 00:00:00Z (more info on Wikipedia).

Epoch-millisecond timestamps are used in:

Statistics Reporting, to filter the results.
Statistics results, such as day-parting or date breakdowns.
Conversions Reporting, to filter the results.
Conversion Report result fields, such as Order Time or Time of Click.

Timestamp ranges for the Katalys API are inclusive, meaning that timestamp ranges should be from 00:00:00 to 23:59:59 of your selected date range to include only the data you wish to return. For convenience, the Katalys API filters accept epoch-seconds or epoch-milliseconds when defining filters. Reporting overall is only accurate down to the second, so there is no difference when using second-resolution 23:59:59 or millisecond-resolution 23:59:59.999.

Example Code

Converting a date-time into epoch-milliseconds is easy with most languages. Below is an example in JavaScript using the Moment library.

JS

const moment = require('moment-timezone');
const mTime = moment().tz("America/Los_Angeles").startOf('day').valueOf();
// define timestamp range for "Previous 7 Days"
const startTime = mTime - (7 * 24 * 60 * 60 * 1000);
const endTime = mTime - 1; // date-range is inclusive, so must exclude 00:00 of next day

Converting a timestamp into a date/time in your local timezone is easy.

JS

for (const reportRow of reportFromKatalysApi) {
  const { orderTime } = reportRow;
  const localTime = new Date(orderTime);
  console.log("Time of order:", localTime);
}

Matching KMP Portal

You can see the KMP portal’s filters in the query-string when you run a report. Review the following example:

https://app.katalys.com/pub/xxx-xxxx-xxxxxxxxxxx/conversions?dims=order_time,order_id,conversion_status,offer,aff,payout,click_time&filters=status!1,9|time!1748761200000,1748847599999!range

The values 1748761200000,1748847599999 are the start and end times in epoch-milliseconds shown in the portal’s view.

Daylight Savings Time

The reporting portal by default uses the US/Los_Angeles timezone (also called “Pacific Time”). This timezone has a daylight savings time adjustment during the months March thru November. Epoch times have no such adjustment, so the KMP portal handles this by changing the passed epoch-milliseconds into the API to match user expectations.