Datetimes In Zuora

From API Documentation

Due to the native data type in SOAP, all dates passed to and from Zuora are datetime stamps, which include a date, a time, and an optional time zone/offset. Zuora's servers operate in GMT-8 time zone, and all datetime stamps returned from Zuora are given in GMT-8, whether or not a time zone is returned.

Note that Zuora charges based on the number of calendar days, and time of day does not impact billing. Whether a charge begins at 4 PM or 4 AM on a given day, Zuora will calculate the charge the same. However, dates passed into Zuora with different time zones are converted to Zuora's GMT-8 time zone, which could potentially change the calendar (for example 1:30 AM December 1 in Greenwich Mean Time (such as London) is 5:30 PM November 30 in GMT-8. In this case, billing can be impacted. See below for best practices in working with different time zones to ensure proper billing.

Note: 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.

Inputting Datetimes to Zuora

All datetimes sent to Zuora will be converted to GMT-08:00. For example, the following datetime: 2009-01-01T03:18:09Z

will be stored as 2008-12-31-T19:18:09-08:00

Please note that a subscribe() call like the following:

<ns2:Subscription>
    <ns1:AutoRenew>true</ns1:AutoRenew>
    <ns1:ContractAcceptanceDate>2009-01-01T03:18:09Z</ns1:ContractAcceptanceDate>
    <ns1:ContractEffectiveDate>2009-01-01T03:18:09Z</ns1:ContractEffectiveDate>
    <ns1:InitialTerm>12</ns1:InitialTerm>
    <ns1:Name>A-S00000020090703080755</ns1:Name>
    <ns1:RenewalTerm>12</ns1:RenewalTerm>
    <ns1:ServiceActivationDate>2009-01-01T03:18:09Z</ns1:ServiceActivationDate>
    <ns1:TermStartDate>2009-01-01T03:18:09Z</ns1:TermStartDate>
   </ns2:Subscription>

will create the subscription, and have the start date and all other dates set to December 31, 2008. Moreover, if the BillCycleDay were set to 1, the start date and bill cycle day are not aligned.

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:

Overview and Best Practices

• Zuora converts all datetimes in a different time zone to GMT-8
• Zuora treats any timestamp without a time zone (such as 2009-01-01T03:18:09) as GMT-8 (ie, 2009-01-01T03:18:09-08:00)
• Zuora billing is NOT dependent on time of day.
• To alleviate any issues with potential mistranslations with time, it is recommended that do one of the following:
  • DO NOT PASS A TIME ZONE/OFFSET. When passing a datetime, strip off any offset, such as 2009-01-01T03:18:09
  • CHANGE YOUR OFFSET TO GMT-08. For example, if your server time is 2009-01-01T03:18:09+02:00, do not translate it to GMT-8, rather just switch the offset, such as 2009-01-01T03:18:09-08:00.

If you stick to one of the two methods above, you can be assured to always have the correct day in Zuora.

Reading Datetimes from Zuora

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

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

will be returned as:

2010-12-31-T19:18:09

Note that there is no time zone attached. Be careful not to 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