Happy Business Starts Here

Highlighted
Community Manager

Date Format and Datetimes in Zuora

This information is documented in the  Zuora Knowledge Center: 

http://knowledgecenter.zuora.com/CB_Billing/WA_Dates_in_Zuora/A_Date_and_dateTime_Format

 

Summary


Zuora uses the MM/DD/YYYY date format, and the GMT-08:00 timestamp. Zuora's servers operate in the GMT-8 time zone. All datetime stamps returned from Zuora are in GMT-8, whether or not a time zone is returned. In Zuora, dates change at midnight (12:00 AM), which is considered the beginning of the day. A period of time that extends from January 1 through February 1 begins at midnight January 1 (immediately after 11:59 PM, December 31), and terminates at midnight between, February 1 (immediately after 11:59 PM, January 31).
Zuora creates charges based on the number of calendar days, and the time of day does not affect billing. Whether a charge begins at 4 PM or 4 AM on a given day, Zuora calculates the charge in the same way. However, dates with different time zones passed to Zuora via the SOAP API are converted to Zuora's GMT-8 time zone, which could potentially change the calendar and affect your billing operations.
For example, 1:30 AM December 1 in Greenwich Mean Time is 5:30 PM November 30 in GMT-8.

 

Daylight Saving Time


For all user-generated data, Zuora does not correct for Daylight Saving Time. When Daylight Saving Time is in effect in the United States, you should adjust your timestamps to account for this.
However, the Zuora servers generate timestamps based on server time, which is set to account for Daylight Saving Time. The Zuora applications assume that all timestamps are in PST.
For example, if a subscription is created at 8:00am PDT (GMT-7:00) on 8/29/2011, the value of CreatedDate will be 08-29-2011 08:00:00 (August 29, 2011 at 8:00am). When this value is queried through the API, it return a GMT-8 timestamp despite being created using a GMT-7 timestamp. This affects only system-generated dates. This does not affect any user-generated dates: Contract effective, service activation, and other user-generated dates are not affected.

 

Important: This does not affect billing operations in any way. The server-generated timestamps are not used in billing calculations.

 

Fields Affected by Daylight Saving Time

The following system-generated fields will return a GMT-7 value when Daylight Saving Time is in effect in the United States:

Object Field
All objects CreatedDate, UpdatedDate
CreditBalanceAdjustment AdjustmentDate
Invoice PostedDate
InvoiceAdjustment CancelledOn
InvoiceItem ChargeDate
InvoiceItemAdjustment CancelledDate
Refund RefundDate
Subscription OriginalCreatedDate, VersionCreatedDate
Usage SubmissiondateTime

 

Best Practices for Using Dates in Zuora

The following best practices for working with different time zones will help prevent billing errors related to datetimes.

  • Zuora converts all datetimes in a different time zone to GMT-8
  • Zuora treats any timestamp without a time zone (such as 2011-01-01T03:18:09) as GMT-8 (ie, 2011-01-01T03:18:09-08:00)
  • Zuora billing is not dependent on the time of day.

To reduce potential mistranslations with time, Zuora recommends that you use one of the following methods when working with datetimes:

  • Do not pass a time zone/offset value: When passing a datetime, remove any offset value. For example, 2011-01-01T03:18:09
  • Change the offset to GMT-08: For example, if your server time is 2011-01-01T03:18:09+02:00, do not translate it to GMT-8. Instead, switch the offset, such as 2011-01-01T03:18:09-08:00. 

Reading Datetimes from Zuora

All datetimes read via query() from Zuora are returned in GMT-08:00. To overcome the SOAP native field limitation, a time zone offset is not returned for select fields.

For example, if the following date stored in Zuora:

2010-12-31-T19:18:09-08:00 

This date will be returned as:

2010-12-31-T19:18:09 

Note that there is no time zone attached. Do not interpret this date as UTC/GMT. The following fields do not return a time zone offset:

  • Amendment.TermStartDate
  • CreditBalanceAdjustment.AdjustmentDate
  • InvoiceAdjustment.AdjustmentDate
  • InvoiceItem.RevRecStartDate
  • InvoiceItem.ServiceEndDate
  • InvoiceItem.ServiceStartDate
  • Product.EffectiveEndDate
  • Product.EffectiveStartDate
  • ProductRatePlan.EffectiveEndDate
  • ProductRatePlan.EffectiveStartDate
  • Refund.RefundDate
  • Subscription.CancelledDate
  • Subscription.SubscriptionEndDate
  • Subscription.SubscriptionStartDate
  • Subscription.TermEndDate
  • Subscription.TermStartDate


Subscribe to Zuora System Updates at Zuora Trust
Follow Zuora Global Support on Twitter and LinkedIn

Tags (3)