Developer FAQs for Zuora Billing

Welcome! This FAQ is for developers starting with Zuora Billing. While Zuora offers several products like Zephr, Revenue, Payments and Togai, this document specifically focuses on Zuora Billing, the product responsible for generating invoices.

If you're looking for a secure, compliant, and reliable solution to automate your company's invoicing, you’re in the right place.

Prefer listening over reading? Log onto Zuora Community and listen to our podcast for Zuora Billing FAQ!

New to Zuora Billing?

What is Zuora Billing?

Zuora Billing automates invoicing and payments at scale, allowing customers to place orders, be invoiced, and make payments automatically. It’s a secure solution, meeting industry standards like SOC and PCI, and backed by a public company with transparent financials.

For a quick introduction, take our tour. No sales pitch—just a very brief view of some essentials. You can provide your email afterward if you want more information.

Why switch to Zuora Billing?

Your current system may struggle with recurring or usage-based billing, scaling to millions of invoices, or maintaining security and compliance (for example, PCI). Zuora Billing handles these challenges seamlessly.

New to billing systems?

Start with this two minute video, then the tour, then our Get Started guide, which covers the basics of using Zuora Billing with REST APIs. You can also review the object model to get familiar with how Zuora structures data, but remember for later that the standard objects can have custom fields of your design added and you can add your own integrated objects.

Why not build my own solution?

Building a homegrown billing system is possible, but it’s resource-intensive and risky. Zuora handles billing and compliance, so you can focus on developing your product, not your billing infrastructure.

Is Zuora too complex?

Zuora’s rich functionality may seem complex, but our Get started guide will walk you through essential setup, such as OAuth authentication and API/SDK calls. Our customers submit millions of API calls to Zuora every day—you can, too.

Multilingual and multi-currency support

Zuora’s global language and currency support lets you bill in the preferred currency and language of your customers. Our User Interface supports 5 languages across 105 locales for localized translations & formatting including Japanese, French, and Spanish.

Looking for a cheat code to integrating?

Zuora has 80+ connectors to App Stores, CRMs, ERPs, Payment Gateways, Tax Systems, Warehouses and beyond. Every quarter Zuora launches new connections to the most requested systems. Check them out here.

Getting Started With Zuora Billing API – MUST READ

Do you have SDKs?

Yes, we’ve got SDKs for Java, Node.js, Python, and C#. But if you prefer more control, our REST API is OpenAPI-compliant, so you can generate your own libraries.

What can I do with the Zuora Billing API?

You can create, query, and update objects like customer accounts, orders, subscriptions, invoices, and memos. For efficiency, you can also use endpoints like POST v1/orders to handle multiple actions (e.g., create an account, order, subscription, invoice, and collect payment) in one go. We know, you want to jump in there right now, patience, start with Get Started, baby steps.

Why are there two APIs — Quickstart and v1?

Quickstart API is great for simple eCommerce use cases (think customer portals) and is quicker to implement. v1 API gives you full control and access to all of Zuora Billing’s features.

Quickstart is for speed; v1 is for depth.

What language support is available?

Besides SDKs, our OpenAPI spec lets you generate libraries for whatever language you're most comfortable with:

• V1 API download
• Quickstart API download

How do I make my first API call?

Check out the Get Started tutorial to grab an OAuth token and make your first call.

How do I get API credentials?

You’ll get an email to set up your password for Zuora. If you don’t have one, hit up your admin or account team. Once you're logged in, you can generate OAuth credentials. The Get Started guide covers this.

What are the base URLs for environments?

The base URL depends on your assigned data center. Compare your UI login with the "Tenant UI Login" tables in the Zuora UI. Pro tip: using the wrong URL is a common cause of 'invalid credentials' errors. Also, don’t store real credit card data in sandboxes. Until you are ready, avoid the Production URLs.

What are the different types of Sandboxes?

• Central Sandbox : Refreshable from production, includes billing accounts/orders, but scrubs sensitive data.
• Developer Sandbox : Only production settings, no customer data.
• API Sandbox : No refresh, limited data and capacity.

There’s much more detail on the differences between each here.

Do I have a UAT environment?

If you’ve got a Central Sandbox, that can be your UAT. Every Zuora Billing customer receives one production and at least one sandbox. If you don’t have sufficient sandboxes for everyone’s needs, you can buy more if needed. Contact your Zuora account team.

Why doesn’t Zuora host my custom code?

Zuora’s Workflow engine automates tasks via a drag-and-drop interface and API access. You can test workflows in Sandbox environments. You can also embed custom rules into business objects to trigger actions automatically.

Getting Started with Zuora Billing SDKs and Libraries

Are there official SDKs or client libraries available?

Yes, they’re available here.

Which programming languages are supported?

We support Java, Node.js, Python, and C# (coming soon).

I prefer using the API directly, not SDKs.

That’s cool—the SDKs are optional. Check out our API options in the section above.

What if my language isn’t supported by an SDK?

No problem. Our API follows the OpenAPI standard, so you can generate libraries for any language you prefer.

• V1 API download
• Quickstart API download

What can I do with the API?

Pretty much everything. You can create accounts, capture orders, generate invoices, handle memos, collect payments, modify product catalog items, manage usage records, create webhooks, adjust tenant settings, and even create custom objects. Whatever you need to do in Zuora Billing, the API has you covered.

Where’s the API reference?

It’s in the Developer Center. But first, decide which API or SDK you want to use by checking out the Get Started section.

Does Zuora Billing support idempotent endpoints?

Yes, the details are here.

Zuora Authentication

What authentication method does the API use?

We recommend OAuth 2.0, though some APIs also support basic authentication. Avoid using basic auth since passwords expire, which could break your integration.

How do I include authentication in my API requests?

First, get your OAuth client ID and secret, then obtain a token and include it in your requests using the Bearer token header.

Zuora Platform Rate Limiting

What are the rate limits for the API?

The Rate Limits section in the documentation has the details.

How can I monitor my current API usage?

Use the System Health Dashboard in your tenant’s admin panel.

What happens if I exceed the rate limit?

You’ll get a "request limit exceeded" error. Use a retry strategy with exponential backoff or consider caching. For persistent issues, contact your Zuora account team.

Can I avoid rate limits?

Yes, by using asynchronous API calls.

Zuora Billing Endpoints

Where can I find a complete list of API endpoints?

Check the API Reference section for a full list. Root URLs vary by data center and tenant type (Production vs. Sandbox).

• V1 API
• Quickstart API

What’s this about SDKs?

For more on SDKs, see the SDK FAQ section.

How do I use pagination with the listed endpoints?

The summary is here.

Data and Date Formats

What data format does the API use?

JSON for nearly everything, except if you’re using the old SOAP API (which we highly recommend you avoid).

How should dates and times be formatted in requests and responses?

Dates and timestamps vary. Transactions usually have just a date (e.g., order date), while objects like invoices have timestamps (e.g., createdDate). More details are here.

Error Handling

What are common error codes and their meanings?

There’s a summary with sample code here and more details on specific codes here.

At what point should I worry about error messages?

If you start getting "Danger! Danger, Will Robinson!" errors, it’s way past time to pay attention.

Webhooks - Notifications - Events

Do you support webhooks?

Yes. We call them "event-based notifications," but they work the same way—triggered when something happens (e.g., an order is saved, an invoice is posted). You can also create custom notifications or use the API to define webhooks.

How do I set up webhooks?

You can set them up through the UI or the API.

Versioning

How is API versioning handled?

V1 versioning is explained here.

How will I be notified of API changes or deprecations?

We post updates in the Zuora Community. You can sign up there for email notifications of future changes.

Where are the changelogs?

• V1 API changelogs
• Quickstart API changelogs

Support and Resources

How do I get help if I encounter issues?

Log into the Zuora UI, click the '?' in the top-right corner, and either use the AI support bot or create a ticket. If you’re a customer an email to support@zuora.com should also work.

How can I check for service issues?

Register at trust.zuora.com for real time updates and a history of service issues.

Are there community forums or developer resources?

Yes, we have a developer forum. Registration is required.

Can I sign up for training?

Zuora University offers free self-paced courses. If your company has a subscription, you can also join live training and take certification exams.

What are good classes to start with?

Start with this list of classes for developers. But treat this list as a menu from which you should choose topics of interest, don’t try to work through them all linearly. But start with these three before jumping to other topics:

• Introduction to Zuora - Some basics on what’s different about Zuora.
• Zuora’s Object Model - Quick run through of main Zuora Billing objects.
• Standard Zuora Architecture - how Zuora typically integrates with your systems.

Security

Is API traffic encrypted?

Yes, all data is encrypted in transit (via HTTPS) and at rest.

What about PCI compliance for credit card data?

Zuora is PCI certified. We run our own credit card vault and allow seamless switching between payment gateways.

Testing

Is there a sandbox environment for testing?

Yes, every customer gets one production and one sandbox tenant (or more if purchased). You can tell by looking at the URL—sandbox URLs usually include 'sandbox' or 'test'.

How do I test my code?

Check out this article on testing and deployment best practices.

How do I move my new code to production?

Make sure your code can switch between sandbox and production endpoints. If your code depends on new features or settings, use our Deployment Manager to sync them.

How does Zuora roll out new features?

New features are released quarterly to Sandbox first, then to Production the following month. Features may require additional steps to enable.

How do I do DevOps with Zuora Billing?

We have a group of features applicable for DevOps, this is a great summary on how we think about DevOps. We also offer git integration built into Deployment Manager.

Billing and Usage

How is API usage billed?

Zuora doesn’t charge for API usage. Instead, we focus on invoice volume, we only succeed if you succeed. API governor limits are in place, but we’ll work with you if there are issues.

How can I monitor my API usage?

Check the System Health Dashboard in the Zuora UI under 'Administration.' There’s one dashboard dedicated to API usage.

How do I use Zuora to bill my customers?

See the Get Started section.

Orders - Subscriptions - Invoices

What’s the deal with orders vs. subscriptions?

An order records what the customer wants (items, quantities, prices), and a subscription is created if there are recurring billing elements (e.g., monthly or annual charges). Orders can also modify existing subscriptions, for example change the quantity or price, or add an additional product or service. An order can also be configured to trigger billing/invoicing either immediately or at a later date.

Study guide

Answer the following questions in 2-3 sentences each:

1. Why are there two main Zuora Billing APIs (Quickstart and v1), and what are the key differences between them?

2. Explain how OAuth 2.0 is used for authentication with the Zuora Billing API.

3. What are the three types of sandboxes available in Zuora, and what are their primary purposes?

4. Describe how webhooks function in Zuora Billing and provide an example use case.

5. What happens when a client exceeds Zuora API rate limits, and what are some strategies to handle this situation?

6. Where can developers find information about API changes?

7. Describe the recommended approach to testing code before deploying it to the production environment in Zuora.

8. Where can developers find support resources and training materials for the Zuora Billing API?