Dates and Times

Response dates and timestamps

Every timestamp field in API responses is an ISO-8601 string in UTC (ends with Z), for example 2024-07-02T14:30:00.000Z.

Some fields are date-only (YYYY-MM-DD) — for example invoice invoiceDate / dueDate. These are calendar dates, not UTC instants.

Date-range query parameters

Endpoints that filter on stored timestamps (such as GET /v2/transactions startDate / endDate) accept two input formats:

There is no timezone query parameter. Calendar-day and ISO filters both use UTC.

Examples (GET /v2/transactions)

# All transactions on July 2, 2024 UTC
curl -G https://api.benjipays.com/v2/transactions \
  -H "x-api-key: YOUR_KEY" \
  --data-urlencode "startDate=2024-07-02" \
  --data-urlencode "endDate=2024-07-02"

# startDate only — inclusive lower bound, no upper bound
curl -G https://api.benjipays.com/v2/transactions \
  -H "x-api-key: YOUR_KEY" \
  --data-urlencode "startDate=2024-07-02"

# Exact UTC window
curl -G https://api.benjipays.com/v2/transactions \
  -H "x-api-key: YOUR_KEY" \
  --data-urlencode "startDate=2024-07-02T07:00:00.000Z" \
  --data-urlencode "endDate=2024-07-03T06:59:59.999Z"

startDate and endDate are each optional. Missing start means no lower bound; missing end means no upper bound.

Endpoints that differ

• Emails (sentStart / sentEnd): same two formats; each bound optional.
• Invoices (invoiceDateStart / invoiceDateEnd, dueDateStart / dueDateEnd): calendar days (YYYY-MM-DD) compared to stored date fields (not timestamp day bounds). Each bound is optional.
• Usage: month-based YYYY-MM-DD rules; see that operation's docs.

Always read the OpenAPI description on each date parameter for the formats that endpoint accepts.