Understanding begin_time and end_time in List API Requests

Many Recurly API list endpoints support the optional parameters begin_time and end_time. These parameters allow you to filter results to a specific time window.

Confusion often comes from not knowing which timestamp field these parameters apply to or how the time range is interpreted. This article explains how begin_time and end_time work in list API requests and how to use them correctly.

How begin_time and end_time Work

When included in a supported list API request, begin_time sets the earliest creation timestamp to include, and end_time sets the latest creation timestamp to include.

GET /accounts?begin_time=2024-01-01T00:00:00Z&end_time=2024-01-31T23:59:59Z

In this example:

• begin_time includes records created at or after 2024-01-01T00:00:00Z
• end_time includes records created at or before 2024-01-31T23:59:59Z

Only records created within that window are returned.

Timestamp Format Requirements

Both begin_time and end_time should be provided in ISO 8601 UTC format.

YYYY-MM-DDTHH:MM:SSZ

Example:

2024-05-01T00:00:00Z

How the Time Range Is Applied

The time window includes records whose creation timestamps fall within the specified range.

GET /invoices?begin_time=2024-02-01T00:00:00Z&end_time=2024-02-02T00:00:00Z

This request returns invoices created:

• On or after 2024-02-01T00:00:00Z
• On or before 2024-02-02T00:00:00Z

Common Sources of Confusion

Filtering by update time instead of creation time

begin_time and end_time do not filter by:

• Last modified time
• Billing date
• Renewal date
• Collection date

If a record was created earlier but updated later, it will not appear in results unless its original creation timestamp falls within the requested range.

Missing records due to pagination

Time filters do not replace pagination. If a request returns multiple pages of results, you must continue paging through the full result set to retrieve all records in the time window.

GET /subscriptions?begin_time=2024-01-01T00:00:00Z

Using local time instead of UTC

A timestamp like 2024-03-01T00:00:00 does not clearly indicate UTC and can lead to confusion when comparing returned results against expected records.

Always convert the time to UTC and include the Z suffix.

Best Practices

• Use ISO 8601 UTC timestamps for all time-filtered requests
• Confirm the endpoint supports begin_time and end_time
• Remember these filters apply to record creation time
• Always paginate through the complete response set when large result volumes are possible
• For recurring exports or syncs, store the latest processed creation timestamp

Example: Incremental Sync Workflow

A common use case is retrieving only newly created records since the last successful sync.

Initial request:

GET /invoices?begin_time=2024-03-01T00:00:00Z

After processing the returned records, store the most recent creation timestamp from that batch.

Next scheduled request:

GET /invoices?begin_time=2024-03-01T01:00:00Z

This helps limit the next request to records created after the previous sync point.

Troubleshooting

If records appear to be missing from a time-filtered list request, verify the following:

• The timestamps are in valid UTC format
• The correct time range was used
• The endpoint supports these parameters
• The expected records were actually created within that range
• All pages of results were retrieved

When to Contact Support

If you still believe records are missing after validating timestamp format, creation time, and pagination, contact Recurly Support with:

• The full API request used
• The affected endpoint
• The expected record UUID(s) or ID(s)
• The begin_time and end_time values used