Whats New

From API Documentation

Jump to: navigation, search


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 & 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 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.
Retrieved from "http://apidocs.developer.zuora.com/index.php/Whats_New"