> For the complete documentation index, see [llms.txt](https://docs.senmo.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.senmo.io/segment-ledger/timestamps.md).

# 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

```
2026-08-05T13:45:27.384Z
```

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:

```json
{
    "id": "txn_01J9R2H3K4M5N6P7Q8R9S0T1",
    "status": "COMPLETED",
    "created_at": "2026-08-05T13:45:27.384Z",
    "updated_at": "2026-08-05T13:45:30.912Z",
    "completed_at": "2026-08-05T13:45:31.104Z"
}
```

***

## Using Timestamps in Requests

Many endpoints support filtering resources using timestamps.

For example:

```
GET /v1/transactions?from=2026-08-01T00:00:00Z&to=2026-08-05T23:59:59Z
```

or

```
GET /v1/statements?start_date=2026-08-01T00:00:00Z&end_date=2026-08-31T23:59:59Z
```

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:

```
2026-08-05T13:45:27.384Z
```

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:

```
2026-08-05T13:45:27.384Z
```

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.