---
updatedAt: 2026-08-05T19:26:09.000Z
---

Fetch the complete documentation index at: https://developer.benjipays.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Dates and Times

How date-range filters and response timestamps work in the Benji Pays API.

## 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:

| Input                                                   | Meaning                                                                                                                                             |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `YYYY-MM-DD`                                            | Full calendar day in **UTC**. Start is `00:00:00.000Z`; end is `23:59:59.999Z`. Passing the same day for start and end returns that entire UTC day. |
| ISO-8601 UTC datetime (e.g. `2024-07-02T07:00:00.000Z`) | Exact UTC instant for that bound. Use this for precise or reconciliation queries.                                                                   |

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

### Examples (`GET /v2/transactions`)

```bash
# 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.