comecerodocs
Concepts

Dates and times

How the Comecero API writes dates in ISO 8601, how the timezone parameter changes them, and the full and shorthand date formats you can send in requests.

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

A date in a response looks like one of these:

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). An account with no time zone uses UTC.

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, such as America/New_York, Europe/Paris or UTC. Daylight saving time is handled for you.

Request
curl "https://api.comecero.com/api/v1/orders/6622-NXKHE-858?timezone=Asia/Kolkata" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"
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.

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.

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

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

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 sendAs date_startAs date_end
20261 January 2026, 00:00:0031 December 2026, 23:59:59
2026-111 November 2026, 00:00:0030 November 2026, 23:59:59
2026-11-077 November, 00:00:007 November, 23:59:59
2026-11-07T1414:00:0014:59:59
2026-11-07T14:3014:30:0014:30:59
today or 0Start of todayEnd of today
yesterdayStart of yesterdayEnd of yesterday
this_week, last_weekStart of the weekEnd of the week
this_month, last_monthStart of the monthEnd of the month
this_year, last_yearStart of the yearEnd of the year
-7Start of the day 7 days agoEnd of the day 7 days ago
+30Start of the day 30 days from nowEnd 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

Carts created yesterday:

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:

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:

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

On this page