*Overview › Further reading*

# Dates and times

> Responses give dates in UTC. When you write, send an ISO 8601 instant with an offset. A bare day such as `2026-10-17` is read in the business time zone of the account when it is in a filter; a write takes one only in a field that is a plain date.

Rental work is organized in days, and a day depends on where the business is. The API therefore separates three things: the instant (exact, UTC), the offset you send with it, and the business time zone of the account, which decides what a bare day means.

## In responses

Dates are ISO 8601 strings in UTC (`date-time`), for example `2026-10-17T08:00:00Z`. Convert them to local time in your own code.

## When you write

Send every date and time as an ISO 8601 instant with an offset, for example `2026-10-17T10:00:00+02:00`. An instant with an offset names the same moment whatever the zone; responses give it back in UTC. The REST contract and the MCP tools require the offset on every date and time you write.

> **Note:** The one exception is a field that is a plain date, with no time: `invoiceDate` and `dueDate` of [`PUT /api/v1/invoices/external/{originSystem}/{originExternalId}`](https://docs.filmo.io/rest-api/endpoint-reference/invoices/create-or-update-the-mirror-of-an-externally-issued-invoice) take a bare day such as `2026-10-17`, with no time and no offset. Anywhere else, if a write with a bare day returns [`validation_error`](https://docs.filmo.io/rest-api/errors/validation_error), add a time and an offset.

## The business time zone

The account has an IANA time zone, which is the one bare days in filters are read in. Read it once from [`GET /api/v1/account`](https://docs.filmo.io/rest-api/endpoint-reference/account/get-the-account), in the `timezone` field, together with the currency and the language. Do not assume it from the country or from the server you run on.

## Date filters on lists

Lists that support them take two families of filters, one for the creation time and one for the last update: `createdOn`, `createdAfter`, `createdBefore`, `createdFrom`, `createdTo`, and the same names with `updated`. Each accepts a bare day, read in the business time zone, or an ISO 8601 instant with an offset.

| Filter | Meaning |
| --- | --- |
| `…On` | Falls on this date. |
| `…After` | Is after this date. |
| `…Before` | Is before this date. |
| `…From` | Is on or after this date. |
| `…To` | Is on or before this date. |

With a bare day, `…After` leaves out that whole day and `…Before` stops at its start, while `…From` starts at the beginning of the day and `…To` includes all of it.

For an incremental sync, [`updatedFrom`](https://docs.filmo.io/rest-api/endpoint-reference/orders/list-orders#param-updatedFrom) and [`updatedBefore`](https://docs.filmo.io/rest-api/endpoint-reference/orders/list-orders#param-updatedBefore) form a half-open window. The guide on [syncing data](https://docs.filmo.io/rest-api/guides/syncing-data) shows how to use them without missing records.

## Dates in MCP tools

MCP list tools take a single `dateFilters` object instead of separate parameters: `dateFilters: { field: { gte, lte, gt, lt, on } }`. A bare day in `gte` or `on` is the start of that business day, and in `lte` the end of that day; `gt` means after the end of that day and `lt` before its start. An instant with an offset is applied as given, except with `on`, which covers the whole business day that contains it.

> **Tip:** If a day-based query returns records you did not expect, check the time zone first: the same bare day covers different instants in different time zones.

---

Canonical URL: https://docs.filmo.io/further-reading/dates-and-times  
Last updated: 2026-10-09