Ctrlk
↪ Back to homepage↗ Help Center
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Timestamps

Segment Ledgers uses the ISO 8601 standard for all date and time values returned by the API.

All timestamps are represented in Coordinated Universal Time (UTC) and include millisecond precision where applicable.

Using a standardized timestamp format ensures consistent behavior across programming languages, databases, and time zones.

Format

All timestamps follow this format:

YYYY-MM-DDTHH:mm:ss.sssZ

Example:

2026-08-05T13:45:27.384Z

Timestamp Components

Component
Description
Example

YYYY

Four-digit year

2026

MM

Month (01–12)

08

DD

Day of month (01–31)

05

T

Date/time separator

T

HH

Hour (24-hour format)

13

mm

Minutes

45

ss

Seconds

27

sss

Milliseconds

384

Z

UTC timezone indicator

Z

Example Timestamp

This represents:

  • Date: August 5, 2026

  • Time: 13:45:27

  • Milliseconds: 384

  • Timezone: UTC

Timestamp Fields

Most resources returned by the API include one or more timestamp fields.

Common examples include:

Field
Description

created_at

The date and time the resource was created.

updated_at

The date and time the resource was last modified.

completed_at

The date and time a transaction was completed.

processed_at

The date and time processing finished.

expires_at

The date and time a resource expires.

Example:

Using Timestamps in Requests

Many endpoints support filtering resources using timestamps.

For example:

or

When filtering data:

  • from or start_date defines the beginning of the time range (inclusive).

  • to or end_date defines the end of the time range (inclusive).

UTC Time Zone

All timestamps are returned in UTC.

The trailing Z indicates that the timestamp is expressed in Coordinated Universal Time.

Example:

This is equivalent to:

Time Zone
Local Time

UTC

13:45:27

London (BST)

14:45:27

Cyprus (EEST)

16:45:27

New York (EDT)

09:45:27

Tokyo (JST)

22:45:27

Applications should convert timestamps to the user's local time zone for display purposes.

Precision

Segment Ledgers stores timestamps with millisecond precision.

Example:

Milliseconds improve the accuracy of:

  • Transaction ordering

  • Audit logs

  • Event processing

  • High-volume financial operations

Sorting

Unless otherwise specified, API resources are returned in descending chronological order, with the newest records first.

Example:

Timestamp
Position

2026-08-05T14:20:12.451Z

1

2026-08-05T14:18:44.093Z

2

2026-08-05T14:17:05.622Z

3

Best Practices

When working with timestamps:

  • Store timestamps in UTC whenever possible.

  • Display timestamps in the user's local time zone only in the user interface.

  • Use the ISO 8601 format when sending timestamp parameters to the API.

  • Avoid relying on string formatting for comparisons; use your language's date/time library.

  • Preserve millisecond precision when storing or processing timestamps.

  • Always use a 24-hour clock to avoid ambiguity.

Supported Timestamp Examples

Description
Example

Resource created

2026-08-05T13:45:27.384Z

Transaction completed

2026-08-05T13:46:08.912Z

Date filter start

2026-08-01T00:00:00Z

Date filter end

2026-08-31T23:59:59Z

Current UTC time

2026-08-05T14:15:00.000Z

Why UTC?

Using UTC as the standard time zone provides several benefits:

  • Eliminates ambiguity caused by daylight saving time (DST).

  • Ensures consistent timestamps across distributed systems.

  • Simplifies auditing and reconciliation.

  • Enables reliable sorting and comparison of events.

  • Makes integrations predictable regardless of where clients are located.

By standardizing on ISO 8601 timestamps in UTC, Segment Ledgers ensures that all financial events are recorded consistently and can be interpreted accurately by clients in any region.

PreviousErrorsNextLedger

Last updated