About DavidW

DavidW

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

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.

DavidW · ‎10-09-2018

Thanks for the update @Christian. Is it possible to show the URL of the POST request and the GET request? That should help to narrow down where the issue lies.

DavidW · ‎09-29-2018

Hi @Christian, Would you be able to provide a bit more info about the steps you're going through, and if possible the REST API endpoint that's being called? I'm afraid I'm not familiar with Pentaho. But those details may help to narrow down the issue. Thanks!

DavidW · ‎09-21-2018

Hi @rudrvij, The two API operations have different use cases: CRUD: Create Account is useful if you just want to create an account object within your Zuora tenant, without creating any associated objects (e.g., subscriptions). For new integrations with Zuora, we recommend using a newer alternative such as "Create account" if appropriate. Create account is specifically designed to create an account complete with credit card information, contact details, and optionally an associated subscription. It's useful if you want to sign-up a new customer directly from your website. It sounds like your use case doesn't fall into either of these buckets. Since you want to create an account and subscription at the same time, but don't want to provide credit card information for the account, I'd suggest you use the Subscribe operation. This operation enables you to create a subscription along with the account that will own the subscription. Does that work for you? We'll look at improving the API documentation to make it easier to figure out which operation is best in a given situation.

DavidW · ‎09-09-2018

We’ve recently been looking into this issue again. I’m replying in this topic because it still gets viewed often. The ZObject class should extend Dictionary<String, Object> , but swagger-codegen isn’t picking this up from our Swagger spec. As a workaround, you can modify a local copy of the Swagger spec before using swagger-codegen to generate the C# library: Download the Swagger spec. To do this, visit https://www.zuora.com/developer/api-reference/, then click the Download button at the top of the page. Open the downloaded file in a text editor. The file is quite large, so this may take a few seconds. Locate this part of the file: zObject: additionalProperties: description: 'Field of the object. ' type: object In the latest Swagger spec, this part is very close to the end of the file. Add type: object within additionalProperties , like this: zObject: additionalProperties: type: object description: 'Field of the object. ' type: object In addition to zObject , there are some other models in the Swagger spec that contain additionalProperties without type specified. I’d recommend that you modify these models in the same way. All the other affected models are called <name>ObjectCustomFields . E.g., AccountObjectCustomFields , which you should modify to look like this: AccountObjectCustomFields: additionalProperties: type: object description: 'Custom fields of the Account 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. ' description: 'Container for custom fields of an Account object. ' title: accountFieldsCustom type: object After ensuring that every occurrence of additionalProperties has type specified, save the file. Note: If you are using version 2.3.0 or later of swagger-codegen , you will need to remove the additionalProperties blocks entirely. See this post for more information. Use swagger-codegen to generate a C# library. Manually modifying the Swagger spec can be time-consuming, so I’d recommend that you automate the process via a script. Don’t hesitate to reply to this post if you’d like any advice about doing that.

DavidW · ‎09-09-2018

If you use swagger-codegen to generate a C# library from our Swagger spec, you may receive the following errors when compiling the generated library: 'FilterRuleParameterValues.ToJson()': no suitable method found to override The name 'BaseValidate' does not exist in the current context These errors occur with version 2.3.0 and later of swagger-codegen , and occur for classes that extend Dictionary (such as the FilterRuleParameterValues class). You can avoid the errors by using an earlier version of swagger-codegen . Alternative Workaround The errors are caused by swagger-codegen incorrectly interpreting Swagger models that contain additionalProperties blocks. See this GitHub issue for more details. Instead of using an earlier version of swagger-codegen , you can avoid the errors by modifying a local copy of the Swagger spec before running swagger-codegen . You will need to remove all additionalProperties blocks. For instance, replace: FilterRuleParameterValues: additionalProperties: description: 'The following reserved key words should not be used as a parameter name: `AttachmentList`, `RecipientList`, `RecipientType`, `Exceptions`, `OCP_OBJECT_TYPE`, `OCP_OBJECT_ID`, `OCP_TRIGGER_BY`. `Include.Attachment` is a special boolean parameter. By specifying this parameter, you can tell a notification whose event type is based on Invoice to include attachments while sending emails. ' type: string description: 'The parameter values used to configure the filter rule. ' title: filterRuleParams type: object by: FilterRuleParameterValues: description: 'The parameter values used to configure the filter rule. ' title: filterRuleParams type: object This workaround may affect the functionality of the generated library. Please let us know if you have any questions or concerns.

Happy Business Starts Here