Description

This knowledge base article provides definitions and explanations for handling dates and timezones within the software system. It introduces two key concepts: "Accounting Date" and "Timestamp". An Accounting Date is a date-only value (YYYY-MM-DD) without any associated timezone, while a Timestamp is a date and time value (YYYY-MM-DDThh:mm:ssZ) that includes a timezone identifier.

The article also discusses the concept of "Tenant Timezone," a per-tenant setting that controls how Timestamps are input, displayed, and converted to Accounting Dates in the user interface. It clarifies that while Accounting Dates are timezone-agnostic, Timestamps are affected by the Tenant Timezone setting.

Digital Asset Customers: Recommendation is to set your system timezone to UTC as it simplifies reconciling crypto transactions to source data.

Definitions

Accounting Date

A date only value in the format YYYY-MM-DD where there is NO TIMEZONE. For example, if a user in New York views enters an Accounting Date as 2024-03-10. A different user in Hong Kong will also view this Accounting Date as 2024-03-10, in the UI and API.

Timestamp

A date + time value with a timezone YYYY-MM-DDThh:mm:ssZ (Z = timezone identifier)

Tenant Timezone

A per SoftLedger tenant timezone selection available to be adjusted in the System Settings. When no timezone is selected, the default is UTC. The Tenant Timezone will:

Control what timezone Timestamps are input into the User Interface
Control what timezone Timestamps are viewed in the User Interface
Control what timezone Timestamps are presented in, when converted to an Accounting Date. For example when a Crypto Transaction Date is converted to a Journal Entry Posted Date.

How this affects the User Interface/App

Accounting Dates are all input and viewed without any timezone.

Timestamps are input and viewed using the Tenant Timezone value (this is set under System Settings).

Note: When operating with digital assets in the crypto module, it is recommended to keep the Tenant Timezone as a UTC time, as almost all providers return data with a UTC timestamp, and SoftLedger exports data with a UTC timestamp.

How this affects the API

Tenant timezones have no affect on the API.

All Accounting Date values are returned as a string value with no associated timezone.

All Timestamps are returned in ISO 8601 Date and time in UTC format. (ex. YYYY-MM-DDTHH:mm:ssZ)

Timestamp Conversions to Accounting Dates

Timestamps entered for transactions such as Crypto Digital Asset Transactions and Inventory Stock Adjustments are converted to Accounting Dates using the set Tenant Timezone.

Example

A user is working in New York, but has a set tenant timezone for Los Angeles. The user creates a digital asset transaction with the below Date:

Date = 2024-03-18T17:00:00 PDT, which is 2024-03-19T02:00:00Z

From this Date input, the Journal Entry created from this digital asset transaction is then created based on the Timestamp above through the below process:

Extract YYYY-MM-DD from the Timestamp,
- View Database Timestamp2024-03-19T02:00:00Z in the Tenant Timezone2024-03-18T17:00:00 PDT
- Extract Date from it 2024-03-18
Journal Entry Transaction Date = 2024-03-18
Journal Entry Posted Date = 2024-03-18