Whats New

From API Documentation

This topic describes the new features available in Zuora's Z-Commerce API.

New in Version 34.0 (October 2011)

Additional Accounting Code Configuration for Discount Charges

In this release, we have added the ability to define an accounting code for discount charges. Previously, Z-Billing used the accounting code from the regular charge that the discount applied to.

When creating a ProductRatePlanCharge using the Z-Commerce API, you can select whether to copy the accounting code from another (non-discount) charge, or define a dedicated accounting code on the new discount charge.

We have added two read-only fields to the Z-Commerce API to support this feature:

• UseDiscountSpecificAccountingCode on the ProductRatePlanCharge object
• UseDiscountSpecificAccountingCode on the RatePlanCharge object

New Aggregation Commands for Export ZOQL

In this release we have added aggregation commands to Export ZOQL. We have added the following commands:

• sum()
• avg()
• min()
• max()
• count()

See Aggregate Functions for more information.

New in Version 33.0 (September 2011)

New BcdSettingOption Field for the Account Object

We have added the BcdSettingOption field to the Account object. The field is of type string, and can take the values AutoSet or ManualSet. The default value is ManualSet.

When the value is set to AutoSet, you cannot set the billing cycle day (BCD). The BCD value will be populated automatically by Zuora.

See Account for more information.

Support for Query by Invoice ID and Invoice Number

Processed usage records are always associated with a chargeable event item and an invoice item in an invoice.

In this release, we have added the ability to query by Invoice ID and Invoice Number when querying the Usage object.

For example:

SELECT  [usage FIELD]  FROM  Usage  WHERE  InvoiceNumber=  AND  [other condition]  
SELECT  [usage FIELD]  FROM  Usage  WHERE  InvoiceId=  AND  [other condition]  
SELECT  [usage FIELD]  FROM  Usage  WHERE  InvoiceId=  AND  InvoiceNumber= AND [other condition]  
SELECT  [usage FIELD]  FROM  Usage  WHERE  InvoiceId=  OR  InvoiceNumber= AND [other condition]

New in Version 32.0 (August 2011)

Invoice Subscription to Different Accounts

In this release, Zuora has added the ability to invoice subscriptions to different accounts. With this feature, you can configure a subscription in an account to be rated and billed by a billing run initiated from a different account.

Previously, a subscription could have a single owner account. After creating the subscription, you could use an owner transfer amendment to change the subscription owner account. With this release, a subscription has an owner account and an invoice owner account. You can now use an owner transfer amendment to change subscription owner account, the invoice owner account, or both.

The following changes have been made to the Z-Commerce API:

• The Subscription object includes the InvoiceOwnerId field, used to indicate the invoice owner of the subscription.
• The Amendment object includes the DestinationInvoiceOwnerId, used to indicate the destination invoice owner during an Owner Transfer Amendment.

You must have the Owner Transfer Amendment permission to be able to edit and change these fields.

New User Permissions

In this release, we have added the following permissions to the Z-Billing Standard User role:

• Create Customer Account: This permission allows you to create customer accounts.
• Create Contact: This permission allows you to create contacts.
• Create Payment Method: This permission allows you to create payment methods.

These permissions are enabled by default. If a user attempts to create an account, contact, or payment method without the required permission, they will receive a "NO_PERMISSION" exception if they are using the Z-Commerce API.

Controlled Release: Encrypted Data Source Option

Note: This is a Controlled Release feature. Contact Zuora Global Support for information about using this feature.

Zuora has added the ability to export a secure version of encrypted data source fields. In this release, Zuora has added the ability to view and export the AchAccountNumber field of any of PaymentMethod and DefaultPaymentMethod data source objects.

To be able to use this feature, you must sign a security contract with Zuora and store your public key in the Zuora System. Zuora decrypts the fields and exports them to a file. We then encrypt the file using your public key, insuring that the fields are never available in plain text format.

To use this feature, when creating an Export object, set the Encrypted field to "true." Note this "Encrypted" field is a newly added one for this feature

Zuora will create a file with the .gpg extension. You can then use your private key to decrypt the file.

If you exported encrypted fields without specifying the "encryption" option (Encrypt Export or setting Encrypted to "true"), the encrypted fields are masked (replaced with "******").

If you delete the record, the exported file will be removed, but the export record is kept to track all encrypted export history. In the Export history, a lock icon in the File type indicates an encrypted record.

If this feature is not enabled for your tenant, you can use the API to set Encrypted to "true," but the API will return an error message.

The encrypted fields are never selectable in a Z-Commerce API query() operation. If you attempt to select an encrypted field, you will receive an "invalid field" error.

Cancel Electronic Refunds (Chase Paymentech Spectrum Gateway)

Note: This is a Controlled Release feature. Contact Zuora Global Support for information about using this feature.

In this release, we have added the ability to cancel electronic refunds. Currently, this functionality is supported only for the Chase Paymentech Spectrum gateway.

You can cancel processed refunds that have the status "Marked for Submission." You cannot cancel refunds that have been settled by the payment gateway.

To use the Z-Commerce API to cancel electronic refunds, you must pass the refund ID and the refund status.

The following is an example of a SOAP message that sets the status of an electronic refund to "Canceled:"

<soapenv:Body>
 <ns1:update xmlns:ns1="http://api.zuora.com/">
     <ns1:zObjects xmlns:ns2="http://object.api.zuora.com/"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:Refund">
         <ns2:Id>4028923930fdf8a30130fdfc27a30068</ns2:Id>
         <ns2:Status>Canceled</ns2:Status>
     </ns1:zObjects>
 </ns1:update>
</soapenv:Body>

This feature is controlled by a new permission, Cancel Electronic Refund, located in the Refund category. This permission is enabled by default for all tenants who have the Refund permission.

See Refunds for more information about refunds in Zuora.

ZOQL: No Default Value for the Order By Clause

Previously, when using the Zuora Object Query Language (ZOQL), results would not be sorted if you did not specify either ascending (ASC) or descending (DESC) in the order by clause.

In this release, the ZOQL sorts results in ascending order if you do not specify ASC or DESC in the order by clause.

For example, the following two statements will return results in ascending order:

select * from Account order by ID" = "select * from Account order by ID asc

select * from Account order by ID" = "select * from Account

New in Version 31.0 (July 2011)

See the July, 2011 Release Notes for more information about new features in Zuora.

Support for Automated Price Change (Uplift) for Renewed Subscriptions

We have added the following fields to support the ability to apply an automated price change when subscriptions are renewed.

• The PriceIncreaseOption and PriceIncreasePercentage fields of ProductRatePlanCharge. You can use these fields with query(), update(), and create() calls.
• The PriceIncreasePercentage field of the Subscription RatePlanCharge. You can use this field with update(), subscribe(), and amend() calls.

Support for Non-Referenced Refunds for Verifi and Orbital Payment Gateways

We have added the PaymentMethodId field to the Refund object to support electronic credit balance refund.

Ability to Delete Payments

In this release, you can now use the delete() call with the Payment object to delete Voided, Canceled, Error, or Draft payments.

New in Version 30.0 (June 2011)

New Invoicing Options for the subscribe() Call

This release introduces the following changes to the subscribe() call:

• SubscribeInvoiceProcessingOptions: Use this SubscribeOptions setting to set the invoice processing scope to either the Account or Subscription level.
  • Account level: Generate an invoice for all of the subscriptions within the account.
  • Subscription level: Generate an invoice for only the subscription that is to be created in the current subscribe call.
• InvoiceResult: This SubscribeResult option contains the invoice IDs and invoice numbers generated in the current subscribe call.

In API version 30, the invoice ID and invoice number fields returned by a subscribe() call represent the ID and number of that subscription that is created by the subscribe() call.

Support for OR and NOT for Export ZOQL

With version 30, you can use the OR and NOT operators to create compound conditions when using the Export ZOQL. In addition, you can use parentheses to indicate the order of the condition.

See Export ZOQL for more information.

Changes to the Session Token Length

The Session Token is a string that we return during the login process of the API. The session token contains information that confirms that the user making an API request is authenticated. All non-login APIs must pass the session token (received during the login process) as part of the request header.

The session token length is variable. In this release, we have modified the token generation, which results in an increase of the token length. The session token can be up to 512 characters in length. If you want to store the session token on the client side, you must make sure that the storage can accommodate the string of up to 512 characters.

See LoginResult for additional information.

New ProductRatePlanCharge Data Source

We continue to release more data sources that allow you to customize the fields you would like to extract. See Export ZOQL for more information about exporting data sources.

We have added the ProductRatePlanCharge data source this release. Every product can have one or more rate plans, and each rate plan can have one or more rate plan charges. The ProductRatePlanCharge data source includes the following objects:

• Product
• ProductRatePlan

New in Version 29.0 (May 2011)

Customizable Gateway Options for Verifi and CyberSource

Zuora allows you to pass in any value for payments for Verifi and CyberSource. This feature allows you to specify one or more gateway options. For each gateway option, you pass a name and a value. Zuora takes the name and value passes it to the gateway. This allows you to add functionality that supported by a specific gateway but currently not supported by Zuora.

See Customizable Gateway Option Example for an sample use of this feature.

Verifi Payment Processing: Advanced MDF Field Mapping

We now support advanced API fields for passing custom data to Verifi. Any field can be passed to the gateway, including merchant-defined fields. This allows you to leverage advanced gateway features associated to these merchant defined fields or overwrite Zuora standard fields, if desired.

The following fields are passed automatically to Verifi:

Enhanced PayPal Reference Transaction Support

Zuora now supports transacting reference transactions using PayPal's PPREF. (Zuora has always been able to transact using PNREF transactions.) This allows you to store customer-created credit card and reference it using PNREF or PPREF.

The following describes the PayPal products supported by Zuora:

• Websites Payment Pro 2.0 and Payflow Pro BYOB: PayPal supports PNREF for reference transactions.
• Websites Payment Pro 3.0 accounts that are integrated through the Payflow Pro APIs: PayPal supports PPREF and PNREF for reference transactions.
• Websites Payment Pro 3.0 that are integrated directly: PayPal only supports PPREF for reference transactions.

This feature is useful if you have customers in Zuora, you are are transacting against them using PayPal, and you want to add Zuora functionality, but do not want customers to have to re-enter their credit card numbers. You can instead pass the PPREF or PNREF values, and Zuora will use them to create payment methods with a reference transaction. Zuora will then use those values to transact against PayPal and make payments accordingly.

Note that we support only reference number refreshes with the PNREF transactions.

New ProcessingType for InvoiceItem

We added the ProcessingType field to the InvoiceItem object. Use this field to identify charges that are discounts or charges. See InvoiceItem for more information.

New in Version 29.0 (March 2011)

The following fields were added to the Refund object:

See the description of Refund for more information.

New in Version 29.0 (February 2011)

Simplified Data Extraction For Reporting, Analytics and Integrations

Zuora now gives you API access to its new DataSources, prejoined, structured data from Z-Billing and Z-Payments. With DataSources Exports, not only can you extract objects from Zuora like Subscriptions and Account, but you also can easily extract these objects joined to related data, such as Accounts with all Subscriptions and Rate Plan Charges. DataSources Exports allow you to easily extract data from Zuora which can can easily be integrated into your reporting, analytics or other systems.

See Export and Export ZOQL for more information.

Support for PayPal Adaptive Payments

Zuora now now supports PayPal Adaptive Payments, in addition to PayPal Payflow Pro. This allows you to:

• Take advantage of Adaptive Payments features
• Add or supplement your customers payment choices by adding PayPal Adaptive Payments

See Payment Method for more information.

New in Version 28.0 (January 2011)

Simpler Amendments With Greater Control

Zuora now offers a new call, amend(), which allows you to

• Amend Subscriptions in a Single Call
• Preview Changes Prior to Activating Amendment

See Amendment Use Cases and amend() for more details

Greater Fraud Prevention and Control With Payment Methods

Zuora now allows you to collect IP addreses and session IDs of web users who update or enter payment methods. Zuora will now pass this information to gateways that support these fields. In addition, you can also link email addresses directly to a payment method. You still have full control over the Bill-To Contact information, but you can also directly link an email address to a payment method.

Greater Control With Overage Charges

Zuora now gives greater control with overage charges, allowing you to specify how to use unused credits/units, as well as calculating overage charges. See ProductRatePlanCharge and RatePlanCharge for more details.

Programmatic (API) Control over PaymentMethod Retry Logic

You can programmatically control retry logic for payment methods. You can now reset the number of failed consecutive attempts to 0 (helpful when updating PaymnetMethod information after it has reached its maximum number of retries), set the total number of retries, and whether or not the PaymentMethod should use the default retry login. See PaymentMethod for more details.

Ability to Update Usage Records

You can programmatically update usage records after they have been created. Please note that usage records that have been processed (calculated and invoiced) cannot be updated.

New in Version 27.0 (December 2010)

Custom Field Support Of InvoiceItems

You can now add and update custom fields to Invoice Items. This is helpful for many applications, including invoice presentment outside of Zuora, denoting line items for reporting, accounting, taxation or other third party systems, and adding additional information to your invoices.

Set A Custom Billing Period For Your Charges

Zuora further extends the flexibility in the duration of your charges' billing periods. In addition to the standard annual, monthly, semi-annual and quarterly billing periods, you can now set a custom billing period (in months). See ProductRatePlanCharge for more details.

Set Included Units In subscribe() Call

You can override the number of included units of a quantity-based charge when creating a subscription. Simply set IncludedUnits in the subscribe() call. See Subscription for more information.

New in Version 26.0 (November 2010)

Create and update your product catalog

You can now update your product catalog programmatically, including updating pricing information. See Working With The Product Catalog for more information. 

Ability to override the billing day of a charge

Zuora now gives you the option to change the bill cycle day for a charge at the subscription level. You will retain the ability to set it globally in both the product catalog as well as letting it default to the customer account's bill cycle day, but you may now override it as well. See RatePlanCharge for additional information.

Update trigger dates for Subscriptions

Starting with version 26.0 of the API, you can use the update() call to set or update ContractEffectiveDate, ServiceActivationDate and ContractEffectiveDate. The subscription must not have been invoiced or amended.

Custom fields for Invoices, Payments, InvoiceItemAdjustments, and InvoiceAdjustments

You may now query, update and create Invoices, Payments, InvoiceItemAdjustments and InvoiceAdjustments with custom fields. Custom fields can be modified on any status (e.g. draft or posted invoices, draft or processed payments).

Apply CreditBalanceAdjustment to and from Invoices

Starting with version 26.0, you can now create Credit Balance Adjustments for Invoices, either moving credit from an Credit Balance to an Invoice, or vice versa. See Working With Credit Balance Adjustments for more information.

Refund Credit Balances

You may now issue refunds via the API drawing from funds from an Account's credit balance.

Cancel CreditBalanceAdustments

In version 26.0, you can now cancel Credit Balances. See Working With Credit Balance Adjustments.

New in Version 25.0

Simplified amendments

With the latest release, you can now create and activate amendments in a single call. See Amendment Use Cases for how to use this new functionality.

New field PaymentMethod.SkipValidation allows for more granular control over payment method authorization

Zuora now gives you the option to create/update payment methods, even if they do not validate with your Payment Gateway. Thus, you create and update payment methods that do not authorize without having to turn off authorization globally. See Payment Method for more details.

Override quantities for tiered and volume charges for subscribe() call

Starting with version 25.0 of the API, you can now override the starting and ending quantities for the various tiers for tiered and volume pricing charge models.

New in Version 24.0

New InvoiceAdjustment object replaces Adjustment and old InvoiceAdjustmentobjects

With the latest release, Zuora has removed all Adjustments and (old) InvoiceAdjustments from all versions of the API. In its place, a new InvoiceAdjustment object is created. The new InvoiceAdjustment is only available in versions of 24.0+ of the API.

Ability to create InvoiceAdjustments via the API

With the release of the new InvoiceAdjustment object, you can now create adjustments in a single step. Thus, Zuora now allows you to adjust invoices (version 24.0+), as well as invoice line items (version 23.0+), via the API. See Adjusting Invoices for more information.

Subscription.Name is no longer required for subscribe() calls

Subscription.Name is no longer required for subscribe() or subscribeWithExistingAccount(). If omitted, Zuora will auto-generate the subscription name.

New Field - RatePlanCharge.IsLastSegment

A new boolean field has been added to the RatePlanCharge object, allowing to easily query for the last/latest segment for RatePlanCharges.

New in Version 23.0

Payments Simplified - One API call to create payment against an invoice

You can now create payments in a single call with the API. If you are making a payment against a single invoice, Zuora will now handle the creation of the InvoicePayment object for you, as well as marking the payment as processed.

Adjust Invoices By Line Items

With the latest version of the API, not only can you now create adjustments, Zuora gives you the ability to adjust line items of an invoice. This allows you to now programmatically adjust invoices, and doing so at the line item level allows for better accounting and reporting. See InvoiceItemAdjustment for more details.

Native Evergreen Subscriptions

Zuora now natively supports evergreen subscriptions. If your subscriptions are indefinite in length and don't have a true term, you can now mark your subscriptions as such.

Custom Fields For Refunds

Zuora now allows to you to add custom fields to refunds. This allows for better tracking, and storing any additional information on your refunds.

Improved API Payment Support for Orbital and Verifi Gateways

Zuora adds additional fields to the Payment object, SoftDescriptor and SoftDescriptorPhone. These allow passing of additional data to Verifi and Orbital gateways. See Payment for more details.

New in Version 22.0

Programmatic Control of the Product Catalog

You can create Products, ProductRatePlans, ProductRatePlanCharges,and ProductRatePlanChargeTiers. This allows you to easily move/migrate product catalogs from one tenant to another, create products and rate plans on the fly, and extend your product & pricing QA/testing.

Simplified Invoice Payment

You can now process payment for an invoice in a single call, greatly reducing the number of calls and logic to process payment and apply to an invoice.

Improved Payment Reconciliation

Zuora now exposes a new field, Payment.BankIdentificationNumber, which is the first 6 digits of a credit/debit card used for electronic payments. This is helpful when reconciling payments between Zuora and your merchant bank.

New in Version 21.0

No External API Changes in Version 21.0

For all intensive purposes, Version 21.0 of the API is identical to version 20.0. The version was incremented for consistency and for internal purposes.

New in Version 20.0

Greater and Simpler Insight To Subscription Changes

To make it easier to parse past, current and future charges, Zuora has introduced the concept of segmented RatePlanCharges, which show how a charge has changed throughout its lifetime. Previously, multiple queries were needed to parse through amendments, previous subscriptions and old charges to piece together a charge’s history. With segmented RatePlanCharges, a single query will return the entire lifecycle of the charge. Similar to previous behavior, when a charge is amended, Zuora creates a new RatePlanCharge. In version 20.0 however, Zuora will now return multiple segmented RatePlanCharges, each representing a period in the charge’s history. To allow for this new functionality, the following new fields have been added to the RatePlanCharge object:

• EffectiveEndDate – The date when the segment ends/ended.
• EffectiveStartDate – The date when the segment begins/began.
• Segment – The identifying number (order) of the segment. Segments are numbered sequentially, starting with 1.
• Version – The version of the rate plan charge. Each time a charge is amended, a new version of the rate plan changed is created.

Greater Insight and Auditing Controls

Zuora now adds audit to fields to all base objects. With these new fields, you can now track who changed what and when. The following fields are now added to all base objects:

• CreatedDate, DateTime field. The date the object was created.
• CreatedById, Zuora ID. The ID of the user who created the object.
• UpdatedDate, DateTime field. The date the object was created.
• UpdatedById, Zuora ID. The ID of the user who created the object.

Please note that to ensure consistency, the following fields have been deprecated from the Amendment object:

• CreatedBy - Replaced by CreatedById
• CreatedOn – Replaced by CreatedDate
• LastUpdatedBy - Replaced by UpdatedById
• LastUpdatedOn – Replaced by UpdatedDate

Expiring Cursors For queryMore()

To improve performance, Zuora now expires cursors returned by queryMore(). Cursors now expire after 15 minutes of inactivity. Please note that this affects all versions of the Zuora, not just version 20.0.

Greater Control With New API Fields

To improve usability and better tie invoices with payments and adjustments (and taxation for Z-Taxation customers) the following fields have been added

• Invoice.AdjustmentAmount - Read Only
• Invoice.Comments
• Invoice.PaymentAmount - Read Only
• Invoice.TaxAmount - Read Only, only available with Z-Taxation
• Invoice.TaxExemptAmount
• InvoiceItem.TaxAmount - Read Only, only available with Z-Taxation
• InvoiceItem.TaxExemptAmount - Read Only, only available with Z-Taxation

To better integrate with accounting systems, the following has been added to Payment:

• Payment.AccountingCode

To give better insight as to when a customer has paid through, as well as to when Zuora has processed usage charges, the following fields have been added:

• RatePlanCharge.ChargedThroughDate – The date to when the customer account has been billed for this charge. Users wanting to make amendments that do not incur any pro-rated charges will want use this date
• RatePlanCharge.ProcessedThroughDate – The date for which the charge has been has been processed through. When billing in arrears, this will be the same as the ChargedThroughDate. It is also the earliest date a charge can be amended.

These fields allow users to better track billing, and quickly calculate amendment dates that will not incur pro-rated charges.

For simpler naming and greater consistency throughout the API, the following fields now replace previous ones

• RatePlanCharge.OriginalId now replaces OriginalChargeId.
• Subscription.OriginalId now replaces OriginalSubscriptionId.
• Subscription.CreatedDate now replaces VersionCreatedDate.

For better insight and ease of use, ProductRatePlanCharge adds the following fields:

• BillingPeriod. The billing period of the charge (such as Month, Quarter, etc.)
• BillingPeriodAlignment. The alignment of the charge.
• BillCycleDay. Replaces BillingPeriodStart.
• ChargeModel. Defines the charge model, replaces now deprecated field Model.
• ChargeType . Defines the charge type, replaces now deprecated field Type.
• RevRecCode. The revenue recognition code for the charge.
• RevRecTriggerCondition. The trigger condition for when revenue recognition can begin. Allowable values are ContractEffectiveDate, ServiceActivationDate, and CustomerAcceptanceDate.
• Taxable. Defines whether a charge is taxable. For Z-Taxation customers only.
• TaxCode. Defines the tax code for a charge. For Z-Taxation customers only.
• TriggerEvent. Defines when billing for the charge should begin. Allowable values are ContractEffective, ServiceActivation, CustomerAcceptance and SpecificDate.

For better naming consistency, the following fields have been replaced.

• ProductRatePlanCharge.BillCycleDay replaces BillingPeriodStart.
• ProductRatePlanCharge.ChargeModel replaces Model
• ProductRatePlanCharge.ChargeType replaces Type.

Improved Error Handling and SOAP Conformity

To Improve error handling within Zuora, the following changes have been made:

• PaymentMethod.AchAccountNumber field is no longer queryable. Prior to version 20.0, you could query it, but it would only return "<Encrypted>"
• SOAP fault InvalidType has been changed to InvalidTypeFault. This now allows previous SOAP frameworks that couldn’t automatically parse the Zuora WSDL to do so.

New in Version 19.0

Greater precision: Migration from Double to Decimal type for currency and quantity fields

Zuora now uses type Decimal instead of Double for currency and quantity fields, like Account.Balance and InvoiceItem.Quantity in version 19.0+ (older versions will continue to use Double). This ensures the precision and accuracy for these fields. Updated fields are:

• Account.Balance
• Adjustment.Amount
• Invoice.Amount
• Invoice.AmountWithoutTax
• Invoice.Balance
• Refund.Amount
• InvoiceAdjustment.Amount
• RefundInvoicePayment.RefundAmount
• InvoiceItem.ChargeAmount
• InvoiceItem.Quantity
• InvoiceItem.UnitPrice
• InvoicePayment.Amount
• Payment.Amount
• ProductRatePlanChargeTier.EndingUnit
• ProductRatePlanChargeTier.Price
• ProductRatePlanChargeTier.StartingUnit
• RatePlanCharge.DMRC
• RatePlanCharge.DTCV
• RatePlanCharge.MRR
• RatePlanCharge.OveragePrice
• RatePlanCharge.RolloverBalance
• RatePlanCharge.TCV
• RatePlanChargeTier.EndingUnit
• RatePlanChargeTier.Price
• RatePlanChargeTier.StartingUnit
• TaxationItem.ExemptAmount
• TaxationItem.TaxRate
• Usage.Quantity

Greater Insight and Simplified Calculations: Precalculated fields

Zuora has added new fields to give better insight to your customers, as well as reduce the need for calculations that often require a few calls to the Z-Commerce API. New fields are:

• Account.LastInvoiceDate. Determine when an account was last invoiced. You no longer need to query invoices and sort by date, rather you can easily access this from the Account now. This is allows insight into customers of when they were last invoiced, allowing for streamlined logic and processing.
• PaymentMethod.LastFailedSaleTransactionDate. This is the date when the last failed transaction occurred.
• PaymentMethod.NumConsecutiveFailures. This is the number of attempts a payment has been been attempted with this payment method and failed. This useful for any automated dunning or account maintenance processes. It is reset to 0 upon successful payment. No longer do you need to query for failed payments and sum them up.
• Subscription.SubscriptionEndDate. This is the date when the subscription ends/has ended. For active subscriptions, it is the same as TermEndDate. If a customer cancels the subscription prior to completing the term, the SubscriptionEndDate is when the subscription is canceled. No longer do you need to query Amendments to determine when a subscription was canceled.
• Subscription.SubscriptionStartDate. This is the original TermStartDate, or when the initial subscription began. Thus, if a subscription renews, you no longer need to query for previous subscriptions to get the original start date.
• Subscription.TermEndDate. The date of when the current term ends. You no longer need to query Zuora for the term start and term length to calculate this field, rather Zuora calculates it for you.

Greater Security: Role-based API Permissions

Zuora has added the role-based permission to API write access. With this new permissions, API users can be limited to read only actions (i.e., preventing update, delete, create, and subscribe() calls). If you have API scripts or processes that are used for reporting or querying, you can now lock down these users to prevent any accidental changes to data.

New in Version 18.0

Custom fields for Account, Subscription, Product, and ProductRatePlan objects

Zuora now allows you to define custom fields for Account, Subscription, Product and ProductRatePlan objects. You will need to add the custom fields manually to your WSDL to use them via the Z-Commerce API. See Custom Fields for more information.

Improved Country Name for Taiwan

For Contact.Country, Zuora now accepts "Taiwan" as well as the ISO standard "Taiwan, Province of China"

New in Version 17.0

Greater flexibility with triggering charges

Zuora now allows you to specify a specific for when a charge is triggered, in addition to the traditional trigger dates (Contract Effective, Service Activation, and Customer Acceptance). You no longer need to trigger a charge based on one of these dates, and can specify a specific date. See documentation for RatePlanCharge object for more information.

Greater control of tagging and filtering products and products rate plans with custom fields

For customers using custom fields, you can now add custom fields to products and products rate plans. This allows for you to tag and segment your products and rate plans, and hide, expose or highlight them as you see fit. You can query and filter based on the custom fields, as well as update them via the API.

New in Version 16.0

Ability To Delete Subscriptions and Rollback Amendments

Zuora now allows the deletion of versions of subscriptions that have not been invoiced. Deleting the subscription rolls it back to the previous version (undoes an amendment), or if it is the initial version, will delete the subscription entirely. This allows for greater flexibility in undoing amendments, as well as recovering from incorrect subscriptions.

Extended update() and delete() for Product and Product Rate Plan objects

Zuora now allows the updating and deleting of products and product rate plans. Deleting products will remove underlying product rate plans, and can be removed as long as their are no subscriptions attached to that product. Product rate plans can be deleted as long as their are not subscriptions attached to that rate plan. Metadata of these objects can now be updated as well.

New in Version 15.0

Correctly exposed date of when subscription object (version) is created

In version 10.0 of the API, Zuora exposed Subscription.CreatedDate, which pointed to when the base subscription was created. In version 15.0, Zuora has deprecated CreatedDate, and has exposed VersionCreatedDate, which is the date the subscription version was created.

New in Version 14.0

Billing Period Alignment

Zuora now allows you to specify billing period alignment. Previously, you could only align to a charge. Now, you can now align to a charge, subscription start, and term start date. This is most useful when adding charges to a subscription that was previously created.

New in Version 13.0

Less restrictions on contacts

Zuora no longer requires contacts to have email addresses, mailing addresses, or phone numbers. If you are a customer of Z-Taxation, you may be required to set address information. Going forward from version 13.0, contacts need only first and last name. You will need to specify email addresses if you choose to email invoices.

New in Version 12.0

Greater visibility of invoice operations

New fields for invoices - Zuora added additional fields to the Invoice object to give better visibility to who did what and when. These fields include:

• CreatedBy - The ID of the user who created the invoice. If the invoice was generated by a bill run, it is the ID of the user who created the billrun.
• CreatedDate - The date when the invoice was generated
• LastEmailSentDate - The date when the invoice was last emailed.
• PostedBy - The ID of the user who posted the invoice.
• PostedDate - The date when the invoice was posted.
• UpdatedBy - The ID of the user who last updated the invoice
• UpdatedDate - The date when the invoice was last updated.

Differentiation of Adjustments (Credit vs. Debit Memos)

Adjustment.Type now exists to specify credit memos from debit memos.

New in Version 11.0

Call subscribeWithExistingAccount has been deprecated.

subscribe() can be used with existing accounts

Zuora has deprecated subscribeWithExistingAccount(), and has merged this functionality with the subscribe() call. You can now use both subscribe() to create subscriptions for new accounts or existing accounts. This also adds additional support for Microsoft .NET as well.

New call

• generate() can be used to create invoices - Zuora now allows you to create individual invoices via the API. Similar to an ad-hoc billing run for a single account, you can call generate() invoice for an individual invoice. The invoice created will be in Draft status.
• update() invoice.status - You can now update the status of invoices via the API call. Thus, you can post an invoice via the API.

New Fields

• Invoice.IncludesOneTime - Solely used for generate() with invoice, specifies whether or not the invoice generated includes one time fees. Defaults to True.
• Invoice.IncludesRecurring - Solely used for generate() with invoice, specifies whether or not the invoice generated includes recurring charges. Defaults to True.
• Invoice.IncludesUsage - Solely used for generate() with invoice, specifies whether or not the invoice generated includes usage charges. Defaults to True.

New Behavior

Timezones returned for datetime objects - Zuora handles all datetimes in GMT-08, regardless of timezone or daylight savings time, but never returned timezone information. Zuora will now return datetimes formatted similar to 2009-08-26T15:10:32.000-08:00. Please note that no timezone will be returned for the following fields:

• Adjustment.AdjustmentDate
• Amendment.TermStartDate
• InvoiceItem.RevRecStartDate
• InvoiceItem.ServiceEndDate
• InvoiceItem.ServiceStartDate
• Product.EffectiveEndDate
• Product.EffectiveStartDate
• ProductRatePlan.EffectiveEndDate
• ProductRatePlan.EffectiveStartDate
• Subscription.CancelledDate
• Subscription.TermStartDate
• Zuora will be mirgrating most datetime objects to date fields in coming releases, which will remove any inconsistency among timezones and dates/datetime objects.

Improved Performance

subscribe() up to 50% faster - Zuora has refactored the subscribe() call, greatly improving its performance. You should marked improvement in the subscribe() call.

New in Version 10.0

New Object Exposed to Delete()

Usage - You can delete usage via the API. This is useful when testing usage charges and want to clean up the tenant.

New Fields

Subscription.CreatedDate - The date on which the subscription was created. This is useful for querying for new subscriptions and for newly amended subscriptions

REMINDER - When you amend a subscription, a new subscription object is created. It will have the version number incremented by one, and will have the same subscription number as the old one. You can use this field not only to see newly created subscription, but newly amended subscriptions.

New in Version 9.0

New Object

RatePlanChargeData - This is a new wrapper for the subscribe() and subscribeWithExistingAccount calls. This wrapper allows you to pass and override the RatePlanChargeTiers. Applicable for Volume and Tiered based pricing models.

NOTE: If you are upgrading from an earlier version of the API, you many need to update your code for subscribe() and subscribeWithExistingAccount() if you are passing RatePlanCharge objects with these calls.

New Fields

• Payment.GatewayResponse - The message returned from the payment gateway for a given payment, if any. This is gateway dependent.
• Payment.GatewayResponseCode - The response code returned from the payment gateway for a given payment, if any. This is gateway dependent, too.
• RatePlanChargeTier.IsOveragePrice - Denotes if a tier is the overage price. Applies only to tiered pricing with overage.

New in Version 8.0

New Fields

• ProductRatePlanChargeTier.IsOveragePrice - Denotes if a tier is the overage price. Applies only to tiered pricing with overage.
• ProductRatePlanChargeTier.PriceFormat - This specifies what whether pricing is per unit or flat fee. Applies only to volume or tiered pricing models.
• Usage.AccountNumber. We now allow AccountNumber to specify usage data, not just Account.Id.

New in Version 7.0

New Fields

• Account.AdditionalEmailAddresses - This is a string field to specify a list of emails where invoices should be sent. Not very applicable to B2C customers, but if you are selling to an enterprise account, you may want an invoice sent to Accounts Payable and Sold To contact.
• Account.Balance - This is the outstanding balance on the account. This is also a good proxy for customers who may have failed payments if you Autopay is set to True and payment terms are set to Due Upon Receipt. After you've run your payment run, your accounts (most likely) should have a $0.
• Account.InvoiceTemplateId. We now allow invoice templates on a per account (you can now have different invoice templates assigned to different accounts).

New in Version 6.0

New Behavior

Query() will now by default return 2000 results. Prior to version 6.0, only the first 100 results are returned.

New Calls

queryMore() Allows ability to query for more than default number of results returned. This is beta only. Please contact your Zuora account representative if you for access to queryMore().

New Objects

QueryOptions Allows you to specify the number of results returned with the queryMore() option.

New in version 5.0

New Objects

TaxationItem is now available for customers of Z-Taxation, allowing you to handle both taxation and tax exemption.

New Fields

• Account.InvoiceDeliveryPrefsEmail Boolean value that allows to specify if the invoice generated for the account should be delivered via email. Defaults to false.
• Account.InvoiceDeliveryPrefsPrint Boolean value that allows to specify if the invoice generated for the account should be delivered via print (ie, is downloaded via PDF).
• Account.TaxExemptCertificateID String value of the ID of the customer account's tax exempt certificate.
• Account.TaxExemptCertificateType String value for the type of tax exemption certificate.
• Account.TaxExemptDescription String value to describe the tax exemption.
• Account.TaxExemptEffectiveDate Date value for which the tax exemption status becomes effective.
• Account.TaxExemptExpirationDate Date value for which the tax exemption status expires.
• Account.TaxExemptIssuingJurisdiction String value to denote the issuing jurisdiction of the tax exemption.
• Account.TaxExemptStatus String value for the status of the tax exmeption.
• Contact.County String value for county of contact. Used for Z-taxation.
• Contact.Description String value for description of contact.
• PaymentMethod.TaxExemptIssuingJurisdiction This is the CVV/CVV2 code that you can now specify for credit cards. Only used with the PayPal gateway.
• Usage.Description This allows you to give a description to usage uploaded.