Dates and Timestamps


The following guide refers to invoices but is also relevant for other documents like credit notes, receipts, journals and bank transactions (spend and receive money)

The Date element

  • The Date element is optional when creating invoices via the Xero API.
  • If specified the Date element should use the YYYY-MM-DD format e.g. 2013-02-08
  • If the Date element is not specified then the Xero API will automatically populate this with the current date based on the timezone setting of the organisation (you can find the timezone setting of the organisation by going to Settings > Financial Settings in Xero).

    e.g. If an invoice is created for a New Zealand based organisation (with a timezone setting of UTC+12:00) at 9pm 7 Feb 2013 UTC and the date element is not specified then the Date will be set as 8 Feb 2013.

The UpdatedDateUTC element

The UpdatedDateUTC element is automatically populated by Xero (you cannot set it), and is the timestamp of the last edit to the invoice.

Retrieving modified resources

If you are trying to retrieve invoices that have been modified since a certain time we recommend you use a “If-Modified Since filter”

JSON Date format

Unfortunately here at Xero we use .NET, and foolishly used the Microsoft .NET JSON date format available at the time of original development.
We are really sorry about this.

An example UTC date/time in JSON is returned like this:

“DateTimeUTC”: “\/Date(1439434356790)\/”

An example local date/time in JSON is returned like this:

“PeriodLockDate”: “\/Date(1419937200000+1300)\/”

In both cases, the date/time value is a unix timestamp value, but in miliseconds rather than seconds (so divide by 1,000 for seconds).

For times that include a timezone offset (e.g. ‘+1300’), regardless of whether it is a UTC timestamp or local date, you would need to add/subtract the time offset as appropriate to calculate the date or date/time correctly.

In addition to being sorry about this, we are also now bound by the fact that many of our API users are already using the format, so we cannot easily change it.

Experimental API calls

To get more familiar with how invoices and their associated dates/times are generated in Xero using the API, we recommend you use the API Previewer to generate some test invoices with your Xero Demo Company.