About DavidW

DavidW

We just upgraded our Knowledge Center to a new responsive version. Texts, tables, and images in Knowledge Center articles are now automatically optimized for different screen sizes. With the new version comes a new in-page layout (spacing and font sizes): We also took the opportunity to restructure our articles to be aligned with product definitions and to make it easier for you to find the information you need. The most notable change you'll see is the information blocks on the home page of the Knowledge Center. No content changes were made. All the articles in the previous Knowledge Center site can still be found. Even if some articles are moved to different locations, you will be automatically redirected if you access the previous links of the articles. This is part of Zuora's effort to continuously optimize the quality and ease-of-use of our docs. We plan to iterate on the new Knowledge Center layout, so please let us know if you notice anything that could be improved. We'd love to hear your feedback! Feel free to reply to this post or contact us at docs@zuora.com. Thanks!

DavidW · ‎10-07-2019

Hi Stanley, That's great - thanks for confirming it works! Very happy to help out. David

DavidW · ‎10-07-2019

Hi Stanley, Looking in the documentation for Create subscription, it seems that several fields are listed as strings instead of numeric types. This is what's causing 'DiscountPercentage' etc to be strings in the 'POSTScCreateType' class. We'll review the field types to see which ones need changing in the documentation. Thanks for raising this issue. I've investigated the reason why 'quantity' is always included in the JSON that's sent to Zuora from the C# library. The C# library uses Newtonsoft.Json to serialize objects to JSON. By default, Newtonsoft.Json writes null values to JSON when serializing. That means that even if 'quantity' is null in a 'POSTScCreateType' object, the serialized JSON will still include 'quantity' - which I believe is causing the error you're receiving from Zuora. The behavior of the JSON serializer can be controlled by the NullValueHandling setting. Specifically, it seems possible to use JsonConvert.DefaultSettings to override the default behavior and have the JSON serializer ignore null values. After some playing around, I'd recommend that you add this early on in your code (before making any API calls): Func<JsonSerializerSettings> defaultJsonConvertSettings = () => { return new JsonSerializerSettings { NullValueHandling = NullValueHandling.Ignore }; }; JsonConvert.DefaultSettings = defaultJsonConvertSettings; You'll also need to add this line at the beginning of the file: using Newtonsoft.Json; Assuming I've understood the issue correctly, does this workaround do the trick?

DavidW · ‎10-01-2019

Hi @sqian, glad to hear that GETCatalogType is working well. To address your follow up question - I believe you are seeing a mismatch because the ChargeOverride class is not related to "Create subscription". It's related to a different part of the API (specifically, Orders). Instead of the ChargeOverride class, I think you want to look at the POSTScCreateType class. Because in the request body of "Create subscription", the class corresponding to chargeOverrides is called POSTScCreateType. Here's a bit more detail: The class for the request body is POSTSubscriptionType. This class has an attribute called subscribeToRatePlans, which is a list of POSTSrpCreateType instances. The POSTSrpCreateType class has an attribute called chargeOverrides, which is a list of POSTScCreateType instances. Hope this helps!

DavidW · ‎09-23-2019

Hi @sqian, I don't think you missed anything. It looks like you're running into an issue that we also discovered recently. The GETCatalogType class is OK I think. But GETCatalogType has a property called Products, which is an array of GETProductType instances, and GETProductType is missing all the properties id, sku, name and so on. I've attached a modified Swagger spec to this reply. Please could you try regenerating the csharp-dotnet2-client using this Swagger spec and let me know the outcome? Thank you!

DavidW · ‎09-10-2019

Zendesk has recently open-sourced a Ruby interface to Zuora’s REST API. It’s called IronBank: https://github.com/zendesk/iron_bank/ IronBank has a couple of really exciting features: Zuora objects can be queried using Ruby language conventions, with associations defined on objects. E.g., Account objects have a bill_to method that queries the associated "Bill To" contact of the Account. Objects that change very infrequently - notably the product catalog - are cached locally, so that they don’t need to be fetched from Zuora on every request. This is definitely a Zuora best practice! Check out this Medium article from Mickaël Pham at Zendesk for a fantastic introduction to IronBank: https://medium.com/zendesk-engineering/open-sourcing-ironbank-our-zuora-client-cfc0a4562c1b

DavidW · ‎08-29-2019

We've updated the API documentation to include information about setting ProductRatePlanChargeTierData when creating a Product Rate Plan Charge. Please see here: https://www.zuora.com/developer/api-reference/#operation/Object_POSTProductRatePlanCharge

DavidW · ‎05-14-2019

The endpoint POST /v1/object/credit-balance-adjustment is now documented. See here for more details: https://www.zuora.com/developer/api-reference/#operation/Object_POSTCreditBalanceAdjustment

DavidW · ‎05-04-2019

Sounds good @vasudeva_shenoy, thanks. Just FYI - In my previous post I mentioned a separate Swagger spec available at https://assets.zuora.com/zuora-documentation/swagger-codegen-workaround.yaml (in relation to swagger-codegen versions earlier than 2.3.0). We're planning to provide this Swagger file until June 2019. Please let me know if your customer would be depending on us keeping it up to date.

DavidW · ‎05-04-2019

The latest version of swagger-codegen 2.x (version 2.4.5) correctly inserts HashMap<String, Object> in ZObject.java. So there should be no need to apply the workaround described above. When generating a Java code library, you should be able to directly use the Swagger spec located at http://assets.zuora.com/zuora-documentation/swagger.yaml

DavidW · ‎05-04-2019

Hi @Ridhima, It appears that the swagger-codegen developers have fixed the ERRORUNKNOWN issue in the latest version of swagger-codegen 2.x (version 2.4.5). So you should now be able to use this Swagger file without any modifications: https://assets.zuora.com/zuora-documentation/swagger.yaml Please let us know if you still experience any errors. Thanks! David

DavidW · ‎05-04-2019

The issue described above appears to be fixed in the latest version of swagger-codegen 2.x (version 2.4.5). When generating code libraries, you should be able to use the usual Swagger spec, which is located at http://assets.zuora.com/zuora-documentation/swagger.yaml We plan to continue providing the separate Swagger spec (swagger-codegen-workaround.yaml) until June 2019. Please reply to this post if you have any questions or concerns.

DavidW · ‎04-29-2019

Hi @vasudeva_shenoy, do you know whether your customer is using the latest version of the 2.x branch of swagger-codegen or the latest version of the 3.x branch of swagger-codegen? Right now the latest versions are 2.4.5 and 3.0.8 (see here), but csharp support in 3.0.8 is listed as “experimental”. And as far as I’m aware, we haven’t verified whether our Swagger spec is compatible with the 3.x branch of swagger-codegen. Assuming your customer isn’t wanting to use the 3.x branch of swagger-codegen, I’ve got a couple of suggestions for your customer: There is a known bug in version 2.3.0 and later of swagger-codegen that affects ZObject (see here). Would it be possible to use an earlier version of swagger-codegen? If you can use an earlier version than 2.3.0 - You should set type: object within additionalProperties as explained earlier in this thread. This will ensure that the ZObject class extends Dictionary<String, Object> in ZObject.cs: public partial class ZObject : Dictionary<String, Object>, IEquatable<ZObject>, IValidatableObject Otherwise, ZObject won’t extend Dictionary correctly: public partial class ZObject : Dictionary<String, >, IEquatable<ZObject>, IValidatableObject Per my previous post in this thread, you can grab a Swagger spec that already includes the workaround from https://assets.zuora.com/zuora-documentation/swagger-codegen-workaround.yaml. Update 5 May, 2019: We plan to provide this Swagger spec until June 2019. If you can’t use an earlier version than 2.3.0 - additionalProperties will cause compilation errors, so you’ll need to remove additionalProperties . You could replace additionalProperties by all the properties that you anticipate needing to reference in the ZObject class. For example, if you’re going to use Query to always query fields called Name and Status , you could modify the Swagger spec to look like this: zObject: type: object properties: Name: type: string Status: type: string This workaround is not ideal from a flexibility point of view, but it could be your best option. As an alternative suggestion, I am aware of a fork of swagger-codegen 2.x called openapi-generator. I don’t know what the results are like, but would be interested to know whether it improves upon swagger-codegen in terms of compatbility with our Swagger spec. Would any of these suggestions help you to make progress?

DavidW · ‎04-23-2019

As of April 2019, we are providing a separate Swagger spec that has type specified for every occurrence of additionalProperties . It is available at: https://assets.zuora.com/zuora-documentation/swagger-codegen-workaround.yaml Update 5 May, 2019: We plan to provide this separate Swagger spec until June 2019. See this Community post for more information.

DavidW · ‎04-23-2019

As of April 2019, we are providing a separate Swagger spec that includes the workaround described above. It is available at: https://assets.zuora.com/zuora-documentation/swagger-codegen-workaround.yaml Update 5 May, 2019: We plan to provide this separate Swagger spec until June 2019. See this Community post for more information.

DavidW · ‎04-23-2019

Hi again @Ridhima, After further investigation into your issue, it seems like there's a regression in swagger-codegen that's causing the issue. We have logged the issue with the swagger-codegen developers (here) and are now providing a separate Swagger spec that has the workaround applied: https://assets.zuora.com/zuora-documentation/swagger-codegen-workaround.yaml Please use this spec instead of the test spec I sent previously. At this time, we don't plan to update https://assets.zuora.com/zuora-documentation/swagger.yaml with the workaround. Regarding your request about CommonResponseType - I've logged this request internally so that our Documentation team can investigate. The internal reference number is DOC-2534.

DavidW · ‎04-23-2019

Update 5 May, 2019: The issue described in this post appears to be fixed in the latest version of swagger-codegen 2.x. See below for more information. We have identified an issue in the latest version of swagger-codegen 2.x that affects code libraries generated from Zuora's Swagger spec. The issue is known to affect Python and Java libraries. It may also affect other languages. When using a Python library that was generated with swagger-codegen 2.4.4, you will receive an error such as: File "/Users/username/python-client/swagger_client/models/account_object_custom_fields.py", line 19, in <module> from swagger_client.models.errorunknown import ERRORUNKNOWN # noqa: F401,E501 When using a Java library that was generated with swagger-codegen 2.4.4, you will receive an error such as: [ERROR] /Users/username/java-client/src/main/java/io/swagger/client/model/SubscriptionProductFeatureObjectCustomFields.java:[28,83] cannot find symbol [ERROR] symbol: class ERRORUNKNOWN As a workaround, we have provided a separate Swagger spec that avoids the issue. You can use this Swagger spec when generating code libraries: https://assets.zuora.com/zuora-documentation/swagger-codegen-workaround.yaml Our workaround should have minimal impact on the functionality of generated code libraries, but please reply to this post if you do experience any errors or unexpected behavior. For more information about the issue and the workaround we have applied, see https://github.com/swagger-api/swagger-codegen/issues/9379.

DavidW · ‎04-19-2019

Hi @testtest, the subscribes > Account > Id field is documented as of version 2019-04-18 of the API Reference. Please see here: https://www.zuora.com/developer/api-reference/#operation/Action_POSTsubscribe

DavidW · ‎04-09-2019

Hi @Ridhima, After further investigation, it looks like swagger-codegen is not handling additionalProperties blocks correctly. In the Zuora OpenAPI spec, there are several additionalProperties blocks that look like this: additionalProperties: description: 'Custom fields of the Subscription Product Feature object. The name of each custom field has the form <code>*customField*__c</code>. Custom field names are case sensitive. See [Manage Custom Fields](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Manage_Custom_Fields) for more information. ' These additionalProperties blocks do not have a type specified, which is causing swagger-codegen to insert ERRORUNKNOWN into the corresponding Java classes. For example: public class SubscriptionProductFeatureObjectCustomFields extends HashMap<String, ERRORUNKNOWN> Instead, I believe that the classes should extend HashMap<String, Object>. It should be possible to work around this issue by modifying the OpenAPI spec, adding type: object inside every additionalProperties block that doesn't have a type specified. Like this: additionalProperties: type: object description: 'Custom fields of the Subscription Product Feature object. The name of each custom field has the form <code>*customField*__c</code>. Custom field names are case sensitive. See [Manage Custom Fields](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Manage_Custom_Fields) for more information. ' For convenience, I have created a test spec that includes this workaround: https://raw.githubusercontent.com/davidwzuora/swagger-codegen-test/master/zuora-swagger-2019-03-27-java.json Please can you try this spec instead of https://assets.zuora.com/zuora-documentation/swagger.yaml and let me know the outcome?

DavidW · ‎04-08-2019

Hi @Ridhima, thanks for posting about this issue. It looks like the issue you are seeing may be similar to a previously-known issue with generated Java libraries. Please see this post for a potential workaround: https://community.zuora.com/t5/Developers/Java-SDK/gpm-p/23662/highlight/true#M130 We will do further investigation and get back to you.

DavidW · ‎01-30-2019

As of today, you can download the latest version of Zuora's Swagger spec from https://assets.zuora.com/zuora-documentation/swagger.yaml If you currently download our Swagger spec from https://www.zuora.com/wp-content/themes/zuora/yaml/swagger.yaml, we recommend that you start using the above URL instead. Over the next few days, we will redirect https://www.zuora.com/wp-content/themes/zuora/yaml/swagger.yaml to point to the new URL. Please let us know if you have any concerns about this change.

DavidW · ‎01-29-2019

Hi @kopacpetr, Thank you very much for reporting this issue. Please could you submit a request for assistance at https://support.zuora.com/ so that our Support team can investigate further. If you can include as much debugging information as possible, that will help a lot.

DavidW · ‎12-02-2018

Hi @DMeseroll, We recently discovered that the "Try it out" JSON at https://api-docs.io/ does not contain every single field. Apologies for any inconvenience this may have caused you. I'll raise the bug with the company that provides the API doc viewer. As an alternative to using https://api-docs.io/, it's now possible to see the entire JSON inside Postman. Here's how: Download the Postman collection from this Community post, or use this Swagger converter to generate an up-to-date Postman collection. In Postman, navigate to File > Import, then choose the file that you downloaded or generated. You’ll then see a collection called “Zuora REST API (2018-11-15)”, or similar, in the sidebar: Navigate to v1 > orders > Create order, then click Examples and select All request body fields: In the EXAMPLE REQUEST section, select the Body tab: You’ll then see entire JSON for the request body. The entire JSON in Postman includes the fields that might have been missing at https://api-docs.io/. The entire JSON in Postman also includes fields called * , which represent custom fields of various objects. Hopefully this method works well for you. Please let me know if you run into any issues.

DavidW · ‎10-31-2018

Hi @jwilliams, the conf > batchSize field is not shown in the request sample in the docs, but it is documented under REQUEST BODY SCHEMA: Thanks for pointing this out!

DavidW · ‎10-30-2018

Zuora Collect is the complete solution for optimizing recurring collections in the Subscription Economy. Visit the Zuora Knowledge Center to learn more: https://knowledgecenter.zuora.com/CE_Collect Don't hesitate to start a topic here if you have any questions about Zuora Collect. This forum is also the perfect place to share your experience of using Zuora Collect!

DavidW · ‎10-27-2018

Hi @sanketpattekar, That's a good question. Subscriptions are a bit of an exception: instead of CRUD for creating a subscription, there is the Subscribe action: https://www.zuora.com/developer/api-reference/#operation/Action_POSTsubscribe Does this help? By the way, is there a reason that Create subscription (the recommended way to create subscriptions) doesn't fit your use case?

DavidW · ‎10-21-2018

If you use Postman to test the Zuora REST API, you might have tried importing the Zuora Swagger spec into Postman. Importing the Zuora Swagger spec gives you a Postman collection that contains each API operation, but you often need to make a lot of modifications before you can successfully send a request. E.g., you may need to disable the parameters and headers that aren’t required, set the Authorization header, and paste in a request body sample from the API Reference. To make it easier to test the Zuora REST API, we’ve created a collection that requires much less tweaking. Download the collection. To import this collection into Postman, navigate to File > Import, then choose the JSON file that you downloaded. You’ll then see a collection called “Zuora REST API (2018-11-15)”: The collection corresponds to Zuora Release 234 (R234), November 2018. We don’t plan to provide an updated collection for each Zuora release. However, you can generate an up-to-date collection at any time using this Swagger converter. The Swagger converter is based on open source code from the Postman developers. NOTE: The collection and Swagger converter linked above are provided for reference purposes only. We hope that you’ll find them useful, but they aren’t supported by Zuora. If you have any feedback, please reply to this post. Using Postman To get started using Postman to test the Zuora REST API, I’d thoroughly recommend watching @gelaimr's tutorial How to Use Postman. This tutorial includes a demo of how to generate an OAuth token for the Zuora REST API. When you use “Generate an OAuth token” in the collection linked above, Postman saves the generated OAuth token in your active environment. Postman then automatically sets the Authorization header when you send other requests. Visit the Postman documentation to learn more about environments.

DavidW · ‎10-11-2018

Hi @sanketpattekar, The endpoint /v1/describe/{object} (Describe object) returns metadata about individual Zuora objects such as Account, Subscription, and Invoice objects. As you noticed, this metadata sometimes matches the request/response body of a REST API endpoint - as in the case of CRUD: Create Account - but it's not always the case. Most REST API endpoints have request and response bodies that don't exactly correspond to individual Zuora objects. Typically the request and response bodies are more complex, to allow for more powerful functionality. If you want to see metadata for a REST API endpoint, you can find this in the documentation along with the examples. For instance, here's the metadata for the Create account request body (you will need to scroll down in the documentation to view it): And here's the metadata for the Create account response body (you will need to scroll down further and click "200 OK" to expand it): Do you require this metadata in a structured format that you can work with programatically? We provide our REST API documentation in format called Swagger (also called OpenAPI), which contains all of this metadata. You can access our Swagger specification by clicking Download at the very top of the documentation: If you think this may be helpful for you, please let us know more details about your use case. Very happy to discuss it further. Many thanks, and hope this helps!

DavidW · ‎10-11-2018

Hi @aniketkhare, thanks for reporting this. I just tried the same type of request and didn't receive any errors. Please could you submit your issue at https://support.zuora.com so that our Support team can investigate futher.

DavidW · ‎10-11-2018

Thanks for the feedback, @ankurlalit! I'll move this post to the Billing & Payment Ideas area so that our product manager can see it, and so that other people can upvote or add their uses cases.

Happy Business Starts Here