Time

Dates and time can be a complex subject, extra care must be taken when dealing with multiple timezones. It is important to understand how time works in BillForward as all facets of the system, for example renewals, cancellations and fixed-terms, rely on correct date/time usage. BillForward uses ISO 8601 as our time standard.


Date and Date Time

All dates in BillForward are stored as a full date and time, up to second resolution. This precision allows for targeting the time life-cycle events occur, for example the start and end of a subscription and pro-rata charges. All date/times in BillForward are stored and returned as UTC (Further Information) regardless of the physical location of your organization.

When a date/time value is sent to BillForward the timezone will automatically be converted to UTC. If the timezone portion is missing, the time will be treated as UTC. Data is also returned as UTC, if you operate in a different timezone you may need to apply a timezone to the date/time value when rendering the time such that your users get the correct time.

For example 17:00 UTC (5PM) should be displayed as 09:00 (9am) if your users are viewing the page in PST (GMT-8), for example. The vast majority of programming languages support timezone changes.

Due to the ability to target a specific time of the day, subscription in BillForward can be aligned to a specific time zones day easily


Format

Dates times are returned in the format YYYY-MM-DDTHH:mm:SSZ. To break out the component parts:

YYYYThe year component
MMThe month component
DDThe day component
TIndicates the following section is the timestamp.
HHThe hour component
mmThe minute component
SSThe seconds component
ZThe timezone/offset component. This will always be returned as 'Z'. Indicates the timezone is Zulu time. This denotes UTC time zone.

When sending timezones to BillForwarrd the 'T' can be left out and the Z altered to a different timezone/offset.


Gotchas

There are a few gotchas to watch out for when working in time. UTC and GMT are equivalent and people use the names interchangeably. UTC/GMT is not the same as the time in London, England. Time in England varies between UTC/GMT and BST (British Standard Time).

The 'Z' in the time string indicates to the UI that when rendering the date time local machine timezones should be applied to the output, this may or may not be desired. Altering the 'Z' to a fixed offset, for example +00:00 will disable this behaviour.