Skip to main content

How do I create a refund in the Zuora Application and API?


How do I create a refund in the Zuora Application and API?


Creating a refund in Zuora is straightforward. This article also examines a common use case for a refund: early cancellation of a subscription.

In a Zuora context, a refund is used to return already paid monies back to the customer. The reasons for doing this are really business specific but classic examples would be returning funds due to overpayment, or deciding to refund money due to customer dis-satisfaction of some kind.

Note that refunds imply that money has been returned to customers, you should use adjustments (credit memos) if you are issuing credit to customers but are not returning funds to a customer. This is why refunds must be applied against a previous payment and cannot exceed the payment amount.


Creating a refund is straightforward using either the Zuora application or Zuora API. Like payments, there are two types of refunds: Electronic and External. The key point about Zuora refunds is that you can only refund against a prior Zuora payment. Specifying a prior Zuora payment is mandatory when creating a Zuora refund. These are also sometimes known as referenced payments. Should you need to adjust an account balance without a suitable payment to refund you should use an invoice item adjustment instead.

Electronic refunds are partners to a prior electronic payment - an electronic payment being the Zuora term for a payment collected by Zuora using the built-in Zuora Payment Gateway integration. In practical terms this usually means a credit card, debit card or ACH payment that was processed by Zuora. Zuora offers the option of specifying that the refund associated with any particular electronic payment be refunded to that same electronic payment method, hence the term "Electronic Refund."

You are not required to use an electronic refund for an electronic payment, even if the payment was on a credit card. You can specify an external refund instead. An external refund is simply a record in Zuora of a refund that has been or will be made using an external to Zuora refund process. For example, cutting a check and mailing that to your customer should be entered in Zuora as an External Refund. External refunds can give you greater flexibility in how you deliver the refund, whereas electronic refunds will be processed upon creation.

Create a Refund from the Zuora Application

Creating a refund is quite straightforward for the most part. However, the refund screen has two "save" buttons: Create Refund and Create Refund and Adjust Invoice Items.

Create Refund will simply create a refund and reopen the account balance for the refunded amount. So if your received payment was $100 and you create a $40 dollar refund the account balance will immediately increase by $40 when you save the refund. This is often less than ideal, since usually you will want to refund the amount without increasing the account balance.

That is made possible with the Create Refund and Adjust Invoice Items button, which will take you to a second screen and allow you to create specific invoice item adjustments, often referred to as "write downs" or "write-offs," so you can refund without changing the account balance.

Create a Refund using the SOAP API

The API allows you to create a refund using a create() call and all of the above functionality is available. Your refund can be electronic or external and can be for any amount up to the associated payment amount. Using the API you'll also have to create Invoice Item Adjustments of the appropriate amount if you want to emulate the write-off feature described above with the Create Refund and Adjust Invoice Items button.

Early Cancellation

Refunds often become a factor when a customer has unfortunately requested early termination of their subscription. If your business allows this, and many don't, some portion of the recurring charges may need to be refunded to your customer.

Cancelling a subscription via the SOAP API requires a Zuora Cancellation Amendment. Once the amendment has been saved, the next bill run after the cancelation date will pick up on the cancelation and create a negative balance invoice representing a pro-rated credit. If you view this negative invoice in the Zuora application, the More menu now has an option to Transfer to Credit Balance. Once you do this you can optionally refund the Credit Balance or apply the Credit Balance to any other open invoices. Each of these steps is also possible using the Zuora API.

It is often best to invoke a bill run or generate an invoice immediately as part of the cancelation process and to then deal with the negative value invoice as described in the previous paragraph.