ESHOPMANESHOPMAN Logo
Our Blog

HubSpot API Date Calculations: Decoding Time Since and Time Until

HubSpot API Date Calculations: Decoding Time Since and Time Until

Ever scratched your head trying to figure out why HubSpot's API returns a seemingly random number for your calculated date fields? You're not alone. A recent discussion in the HubSpot Community highlighted some confusion around how the API handles 'Time Since' and 'Time Until' calculations, and we're here to break it down for you.

The Issue: UI vs. API Discrepancy

The original poster noticed that while the HubSpot UI beautifully displays the calculated time difference (e.g., '5 days ago'), the API spits out a raw timestamp. Specifically, it returns the epoch timestamp in milliseconds of the starting date, rather than the calculated difference.

This raises a few key questions:

  1. Is this the intended behavior?
  2. Are we, as API consumers, expected to do the math ourselves?
  3. How does this apply to more complex calculated fields?
  4. Is there a secret API endpoint to get the pre-calculated value?

The Answers, Straight from the Community

A helpful community member confirmed the behavior and dug a little deeper. Here's the gist:

  • Intended Behavior? It seems so. While not ideal, the API currently returns the raw timestamp for 'Time Since' and 'Time Until' fields.
  • Client-Side Calculation Required: Yes, unfortunately. You'll need to grab that timestamp and perform the time difference calculation yourself within your application.
  • Complex Formulas: Good news! For custom equation calculation properties (that aren't date-based), the API usually returns the already-calculated value. But you still need to know what the value represents (duration, date, number, etc.)
  • No Magic Endpoint: Sadly, no. There isn't an API endpoint (at least not currently) that hands you the pre-calculated, nicely formatted value you see in the HubSpot UI.

How to Handle Time Since/Until Calculations via the API

So, how do you actually deal with this? Here’s a simple breakdown:

  1. Retrieve the Timestamp: Use the HubSpot API to fetch the property value. This will be a number representing the epoch timestamp in milliseconds.
  2. Convert to Date Object: Convert the timestamp into a date object using your programming language of choice. In JavaScript, you'd use new Date(timestamp).
  3. Calculate the Difference: Calculate the time difference between this date object and the current time (or another relevant date).
  4. Format for Display: Format the resulting time difference for display in your application (e.g., “5 days ago,” “in 2 weeks,” etc.).

For example, if you are building a b2b e commerce web portal that needs to display shipping times based on a calculated date field in HubSpot, you would need to perform these calculations within your portal's code.

// Example (JavaScript)
const timestamp = data.properties.calculateddate2; // Timestamp from API
const date = new Date(parseInt(timestamp)); // Convert to Date object
const now = new Date();
const diff = now.getTime() - date.getTime(); // Difference in milliseconds

// Format the difference (example: days ago)
const days = Math.floor(diff / (1000 * 60 * 60 * 24));
const formatted = `${days} days ago`;

Property Metadata Example

{
  "updatedAt": "2026-02-27T15:48:01.216Z",
  "createdAt": "2026-02-27T15:48:01.216Z",
  "name": "calculateddate2",
  "label": "CalculatedDate2",
  "type": "date",
  "fieldType": "calculation_equation",
  "groupName": "contactinformation",
  "calculated": true,
  "calculationFormula": "date1",
  "dateDisplayHint": "time_since"
}

API Response Example

{
  "id": "202975473963",
  "properties": {
    "calculated6": "2332900",
    "calculateddate2": "1769990400000",
    "calculateddate4": "1772323200000",
    "createdate": "2026-02-17T13:23:56.251Z",
    "hs_object_id": "202975473963",
    "lastmodifieddate": "2026-03-04T13:02:58.856Z"
  },
  "createdAt": "2026-02-17T13:23:56.251Z",
  "updatedAt": "2026-03-04T13:02:58.856Z",
  "archived": false,
  "url": "https://app.hubspot.com/contacts/45447734/record/0-1/202975473963"
}

ESHOPMAN Team Comment

We at ESHOPMAN understand the frustration of inconsistent data handling between the HubSpot UI and API. Having to perform client-side calculations for date fields adds unnecessary complexity, especially when building custom storefronts or integrating with other systems. Ideally, HubSpot would offer an option to retrieve pre-calculated values via the API. Until then, be sure to document this behavior clearly within your integrations to avoid confusion.

While it's an extra step, understanding this behavior ensures your apps display dates accurately. And who knows, maybe HubSpot will streamline this process in the future!

Share: