Timestamp formats

Every timestamp the Zentail API accepts or returns is ISO 8601, in its RFC 3339 form, and v1 and v2 agree on that. Always send a time zone. v2 always answers in UTC, ending in Z. To poll for changes, keep the time of your last successful request and send it back on the next one.

The format

2026-09-22T14:03:11.199Z
2026-09-22T10:03:11-04:00

The date is YYYY-MM-DD, and T separates it from the time, hh:mm:ss. Fractional seconds are optional. The trailing Z means UTC. For any other zone, end with the offset in hh:mm instead.

Outside v1, every timestamp the API returns is normalised to UTC, with fractional seconds only when they are non-zero: 2026-09-22T14:03:11Z, or 2026-09-22T14:03:11.199Z. Parse with a real RFC 3339 parser rather than a fixed-width pattern.

A value that doesn’t parse answers 400. See Errors.

Producing one

datetime.datetime.now(datetime.timezone.utc).isoformat()
# '2026-09-22T14:03:11.199153+00:00'

fmt.Println(time.Now().UTC().Format(time.RFC3339))

date -u +"%Y-%m-%dT%H:%M:%SZ"
# 2026-09-22T14:03:11Z

URL-encode it in a query string

The format contains colons, and an offset contains a +, so encode it in a URL:

curl "https://api.zentail.com/v2/storefront/orders/shipped?lastUpdatedTs=2026-09-22T14%3A00%3A00Z" \
  -H "Authorization: <your token here>"

Polling for changes

Each polling route takes a “changed since” timestamp, under its own name:

Route	Parameter
GET /v2/storefront/orders/shipped	lastUpdatedTs
GET /v2/storefront/listing/product_data/updated	since
GET /v2/inventory	updatedSince

Store the time you sent your first request of each poll. Once you have read every page, send that time on the next poll, less about five minutes. The overlap costs a little re-reading and closes the gap where a slow write lands just behind your timestamp. Your side then has to tolerate seeing a record twice. Pagination covers walking the pages.

Legacy (v1)

v1 validates date-time parameters against this pattern, and date-only parameters against ^(\d+)-(0[1-9]|1[012])-(0[1-9]|[12]\d|3[01])$:

^(\d+)-(0[1-9]|1[012])-(0[1-9]|[12]\d|3[01])[Tt]([01]\d|2[0-3]):([0-5]\d):([0-5]\d|60)(\.\d+)?(([Zz])|([\+|\-]([01]\d|2[0-3]):([0-5]\d)))$

Poll GET /v1/salesOrder with lastUpdatedTs, which moves every time the order changes. Don’t poll on orderTs: it is when the order was placed and never moves, so it hides later changes. Add a status filter to narrow the list, from PENDING_PAYMENT, PENDING, SHIPPED, CANCELLED, RETURNED, REFUNDED and RETURN_REQUESTED.