Skip to main content

Cancel a subscription and refund the end customers automatically

Zuora

Cancel a subscription and refund the end customers automatically

Orders is now generally available.

If you are an existing Zuora Subscribe and Amend customer and want to adopt Orders, see What is Orders Harmonization for more information. If you want to enable Orders, submit a request at Zuora Global Support.

This tutorial demonstrates how to cancel a subscription and subsequently refund the unconsumed part to the end customers by using the Create an order REST API operation. You can specify the amount to be refunded in the request body. Meanwhile, this operation is able to optionally write off any outstanding balances on the invoices associated with the subscription.

Note the following information before you start trying this tutorial:

  • The auto-refund and write-off function is only supported by the Create an order REST API. You cannot perform this task on Zuora UI or by using the Create an order asynchronously operation.
  • The Cancel a subscription tutorial provides general instructions on how to cancel subscriptions without auto refunding. Check Cancel a subscription if you are looking for general information about how to perform subscription cancellation step by step.

How does the auto-refund and write-off during subscription cancellation function work?

Behind the curtain, the following steps are taken automatically after the "Create an Order" operation is issued:

  1. The subscription is canceled and a credit memo is created to cover any unconsumed services of the subscription.
  2. The refund specified in the request body is unapplied from the payments and then returned to the customer account. 
  3. Depending on how you specified in the request, more credit memos could be created to write off the outstanding balances on the invoices.

Prerequisites

Ensure that the following requirements are met:

API configuration guide

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

Required/Optional

Description

refund

Boolean

Optional; Default is false

Indicates whether to refund after the subscription cancellation.

refundAmount

Number

Optional; Default is null; Required if refund is true

Indicates the amount to be refunded.

writeOff

Boolean

Optional;  Default is false

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

writeOffBehavior

Object

Optional; Default is null

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

Note: 

  • 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.

Notes and limitations

Note the following behaviors and limitations when using the “Create an order” operation to cancel subscriptions and auto refund:

  • The API request will not return errors if some of 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 each of the payments evenly.
  • Only electronic payments can be refunded automatically. External payments are not supported for now.

An example of auto-refund and write-off during subscription cancellation

The following subscription will be used in this example:

  • Subscription Term Type: Termed
  • Charge: 1 monthly recurring charge of 100 USD
  • Contract Effective Date: 2022-01-01

An invoice has been generated on the Target Date of 2022-11-30. Therefore, 1100 USD has been billed to the end customer. A payment then has been processed and collected 1100 USD from the customer.

Later, the customer requested to cancel the subscription effective on 2022-04-30 and the agreed amount to be refunded is 800 USD. 

Among the 800 USD, 700 USD is for the seven unconsumed subscription periods; the other 100 USD is compensation that is agreed upon between the vendor and the end customer. This 100 USD will need to be written off from the invoice.

The following example request would help solve the above issue:

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-00000014",
    "accountNumber": "A%00026270",
    "status": "Completed",
    "subscriptionNumbers": ["A-S00020477"],
    "creditMemoNumbers": ["CM100000123"],
    "refunds": [{
        "number": "R-00009564",
        "status": "Success"
    }],
    "writeOff": [{
        "invoiceNumber": "INV00051208",
        "amount": 100.00,
        "status": "Success",
        "failedReason": null
    }]
}

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