# Dates and times (/docs/basic-concepts/dates-and-times)

The API writes every date in ISO 8601 and reads dates in ISO 8601 or a short form such as `2026-11` or `yesterday`. This page shows both, and how time zones affect them.

## Dates in responses [#dates-in-responses]

A date in a response looks like one of these:

```text
2026-11-07T14:36:52Z
2026-11-07T09:36:52-05
2026-11-07T20:06:52+05:30
```

The date comes first, then `T`, then the time on a 24-hour clock, then the offset from UTC. `Z` means UTC. An offset is written in whole hours (`-05`) or hours and minutes (`+05:30`).

Dates are written in your account's time zone, which you set under **Settings > Technical** (`timezone` in [Update technical settings](/api/settings/update-technical-settings)). An account with no time zone uses UTC.

### Choose the time zone of a response [#choose-the-time-zone-of-a-response]

Add `timezone` to any request to get its dates in that time zone. Use a name from the [IANA time zone list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), such as `America/New_York`, `Europe/Paris` or `UTC`. Daylight saving time is handled for you.

```bash title="Request"
curl "https://api.comecero.com/api/v1/orders/6622-NXKHE-858?timezone=Asia/Kolkata" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"
```

```json title="Response"
{
  "order_id": "6622-NXKHE-858",
  "date_created": "2026-11-07T20:06:52+05:30"
}
```

A time zone name that is not known is a `400`.

<Callout>
Parse dates with a date library or `new Date()` rather than by hand. The same moment can be written with different offsets, so compare dates as moments, not as strings.
</Callout>

## Dates in requests [#dates-in-requests]

You can send a date in full ISO 8601 or in a shorthand. Both work in query parameters such as `date_start` and `date_end` and in body fields such as a token's `expires`.

### Full ISO 8601 [#full-iso-8601]

```text
2026-11-01T00:00:00Z
2026-11-01T00:00:00-05:00
```

A date with an offset is read with that offset. A date without one is read in the request's `timezone`, or in the account's time zone when you send none.

### Shorthand dates [#shorthand-dates]

A shorthand date means a whole period. In `date_start` it means the first moment of that period. Everywhere else, `date_end` and body fields included, it means the last moment.

| You send | As `date_start` | As `date_end` |
| --- | --- | --- |
| `2026` | 1 January 2026, 00:00:00 | 31 December 2026, 23:59:59 |
| `2026-11` | 1 November 2026, 00:00:00 | 30 November 2026, 23:59:59 |
| `2026-11-07` | 7 November, 00:00:00 | 7 November, 23:59:59 |
| `2026-11-07T14` | 14:00:00 | 14:59:59 |
| `2026-11-07T14:30` | 14:30:00 | 14:30:59 |
| `today` or `0` | Start of today | End of today |
| `yesterday` | Start of yesterday | End of yesterday |
| `this_week`, `last_week` | Start of the week | End of the week |
| `this_month`, `last_month` | Start of the month | End of the month |
| `this_year`, `last_year` | Start of the year | End of the year |
| `-7` | Start of the day 7 days ago | End of the day 7 days ago |
| `+30` | Start of the day 30 days from now | End of the day 30 days from now |

Weeks start on Monday. Months and leap years are handled for you. Words such as `today` are worked out in the request's time zone.

### Examples [#examples]

Carts created yesterday:

```bash title="Request"
curl "https://api.comecero.com/api/v1/carts?date_start=yesterday&date_end=yesterday" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"
```

Sales for the last 7 full days, and for the last 7 days including today:

```bash title="Request"
curl "https://api.comecero.com/api/v1/reports/sales?date_start=-7&date_end=-1" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"

curl "https://api.comecero.com/api/v1/reports/sales?date_start=-6&date_end=0" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"
```

Sales for all of 2025, Paris time:

```bash title="Request"
curl "https://api.comecero.com/api/v1/reports/sales?date_start=2025&date_end=2025&timezone=Europe/Paris" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"
```

A shorthand in a body field means the end of the period. A secret token sent with `"expires": "+30"` stops working at the end of the day 30 days from now.

A date that cannot be read is a `400`, and so is a `date_start` that is after `date_end`.

## Next steps [#next-steps]

<Cards>
  <Card title="Lists and pagination" href="/docs/basic-concepts/lists-and-pagination" />
  <Card title="Localized formatting" href="/docs/basic-concepts/localized-formatting" />
</Cards>
