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:
| YYYY | The year component |
|---|---|
| MM | The month component |
| DD | The day component |
| T | Indicates the following section is the timestamp. |
| HH | The hour component |
| mm | The minute component |
| SS | The seconds component |
| Z | The 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.