Skip to main content

Cancel subscriptions and refund end customers automatically


Cancel subscriptions and refund end customers automatically

You can cancel a subscription and refund the unconsumed part to the end customers. You can also write off any outstanding balances on the invoices associated with a subscription when canceling the subscription with a refund.

Auto-refund and write-off process during subscription cancellation

If the cancel and refund request, including the write-off setting, is submitted, the refund and write-off process is automatically initiated as follows:

  1. The subscription is canceled.
  2. A credit memo or final invoice is generated depending on the cancellation effective date. The credit memo is generated for covering any unconsumed services of the subscription.
  3. The payment is unapplied from the invoice.
  4. The refund is returned to the end customer account of the payments. 
  5. The credit memo is fully or partially applied to the invoices depending on the refund amount.
  6. Depending on your settings, more credit memos could be created to write off the outstanding balances on the invoices.


For examples of canceling a subscription with different refunds based on the same calculated credit memo, see Examples of canceling a subscription and refunding the end customers automatically.

Notes and limitations

Note the following behaviors and limitations when you cancel a subscription with a refund:

  • Credit Memo, Payment, and Refund custom fields are not supported. If you have any required Credit Memo, Payment, and Refund custom fields, please do not follow the process described in this article; use the existing cancel subscription, payment, and refund process separately.
  • Through the Zuora UI, you can only cancel a subscription with a refund from the reinvented subscription details page of an active subscription. 
  • The API request will not return errors if the refunds or invoice write-offs fail. But details of each transaction will be returned in the response body.
  • In scenarios where multiple payments need to be refunded, Zuora will refund the payments one by one instead of refunding the same amount to payment evenly. The order of refund is determined by the invoice date and invoice balance. Zuora will refund the payment in the latest invoice first. If the invoice dates are the same, Zuora will refund the payment in the invoice with a higher balance first.
  • Only electronic payments can be refunded automatically. External payments are not supported for now.
  • When refunding a subscription that is not invoiced separately, if you do not enable the Invoice Item Settlement feature, you will encounter the following error during the cancel and refund process: "Cancellation/Refund failed because of the following reason: Invoice is linked to multiple subscriptions. Cancellation was not processed." 


Before canceling a subscription with a refund, ensure that the following requirements are met:

  • The Orders feature must have been enabled.
  • The Invoice Settlement feature must have been enabled to access write-off settings.
  • For UI users:
  • Invoices and payments must be issued first. For example, the bill run and payment have been created.

Cancel a subscription with a refund using the Zuora UI

To cancel a subscription with a refund from the reinvented subscription details page, perform the following steps:

  1. On the top-right of the subscription details page, click Cancel. The Cancel Subscription window opens, and the customer account name and account balance are displayed on the top.

  2. In the Subscription cancellation effective date section, select one of the following dates or specify a Specific Date as the cancellation effective date:
    • End of Current Term: The option is unavailable if the subscription is evergreen.
    • Start of Current Term
    • End of Last Invoice Period: This option is unavailable if no invoice is associated with this subscription.
    • Subscription Start Date
    • Specific Date: The default date is today's date.

      An estimated credit amount in the final invoice is calculated based on your selection. 

  3. If Zuora verifies that the subscription is eligible for refunding, the Do you want to refund payment after the subscription is cancelled? section displays, then specify the following options. Otherwise, the section name displays as Do you want to generate the final invoice after the subscription is cancelled? and only the Generate the final Invoicecheckbox displays in this section for your selection.

    • Refund Amount: If you want to refund your payment while canceling the subscription, specify a value in the Refund Amount field less than the payment amount eligible for the refund; If you want to cancel the subscription only without a refund, uncheck the Refund payment.

    • Write-Off Invoice: If you want to write off your outstanding balance, select the checkbox.

    • Reason Code: Specify the reason code to indicate the refund reason. The reason codes are defined in Payments Settings Define Reason Codes

    • Generate the final Invoice: If you want to generate a credit memo or invoice depending on your different settings, leave Generate the final Invoice checked. Otherwise, you can uncheck the checkbox.

  4. If Order and Order Action custom fields were set, update the custom fields in the Additional Information of Order and Additional Information of Cancellation sections, respectively. For more information, see Manage Custom Fields.
    • If required custom fields are applied, the custom fields are displayed in an expanded view. After updating the required custom fields, you can click Show optional fields to expand and update the optional custom fields if applied.
    • If only optional fields are applied, click Expand to view all fields to expand and update the optional custom fields.
  5. Click Submit. The Cancellation Result window opens, where all cancellation results are gathered together.

    You can only access the cancellation results window once. You will be redirected away from this page once you click any link or button in this window.

    Record the cancellation results before clicking any link or button. Otherwise, reopen the subscription details page to find out these results.

    • If your cancellation succeeds, you can view the following steps.   
      • Cancel Subscription: Click the order number link to view the order details. You will see this result only if you don't set refund and write-off settings.
      • Generate and Post Credit Memo: Click the credit memo number link to view the credit memo details.
      • Unapply Payment: Click the payment number link to view the payment details.
      • Refund Payment: Click the refund number link to view the refund details.
      • Related Invoices: Click the invoice number link to view the invoice details.
    • If your cancellation fails, click Retry Cancel to modify and then click Submit again.
  6. Click one of the following:

    • Go To The Cancelled Status Page: The subscription in the cancelled status with its details page is displayed.

    • Stay On Current Page: The subscription in the expired status with its details page is displayed.

Cancel a subscription with a refund using the REST API

Note that you can only cancel a subscription with a refund through the Create an order operation, you cannot perform the task through the Create an order asynchronously operation.

In the request body of the Create an order operation, you need to specify the following nested fields under processingOptions to define refund and write-off related information.

Refund and write-off related nested fields

Field Name

Data Type





Optional; Default is false

Indicates whether to refund after the subscription cancellation.



Optional; Default is null; Required if refund is true

Indicates the amount to be refunded.

refundReasonCode String Optional: Default is null A code identifying the reason for the refund transaction. The value must be an existing payment refund reason code listed in Payments Settings > Configure Reason Codes. If you do not specify the field or leave the field with an empty value, Zuora uses the default payment refund reason code.



Optional;  Default is false

Indicates whether to write off the outstanding balance on the invoice after refunding.



Optional; Default is null

The financial information of the credit memo items that are generated to write off the invoice balance. 


  • All the credit memo items (CMI) that are used to write off the invoice will be applied with the same financial information.
  • The financial information specified here will not be added to CMIs generated from the unconsumed services of the canceled subscription.

See writeOffBehavior in the request body of the Create an order operation for details.

You can view the status of each refund and write-off transaction in the refund and writeOff fields in the response body.

Below is a request example.

Request POST /v1/orders/
Request Body
  "orderDate": "$Today",
  "existingAccountNumber": "$AccountNum",
  "subscriptions": [
      "subscriptionNumber": "$SubscriptionNum",
      "orderActions": [
          "type": "CancelSubscription",
          "triggerDates": [
              "name": "ContractEffective",
              "triggerDate": "2022-04-30"
              "name": "ServiceActivation",
              "triggerDate": "2022-04-30"
              "name": "CustomerAcceptance",
              "triggerDate": "2022-04-30"
          "cancelSubscription": {
            "cancellationPolicy": "SpecificDate",
            "cancellationEffectiveDate": "2022-04-30"
  "processingOptions": {
      "runBilling": true,
        "billingOptions": {
            "documentDate": "2022-04-30",
            "targetDate": "2022-04-30"
       "refund": true,
       "refundAmount": 800,
       "writeOff": true

Note that to use the above request body directly, you need to replace the values, including the pre-defined variables, with your own data.

Below is the response returned:

Response Body
    "success": true,
    "orderNumber": "O-00011123",
    "accountNumber": "A%00027753",
    "status": "Completed",
    "subscriptionNumbers": [
    "creditMemoNumbers": [
    "refunds": [
            "number": "R-00010170",
            "status": "Success"
    "writeOff": [
            "invoiceNumber": "INV00056406",
            "amount": 100.00,
            "writeOffCreditMemoNumber": "CM100000002",
            "status": "Success"

The refunds and writeOfffields display refund and write-off results.