Cancel a subscription and refund the end customers automatically

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:

• The Orders feature must have been enabled for your tenant.
• The Invoice Settlement feature must have been enabled for your tenant.
• The Invoice Item Settlement feature must have been enabled for your tenant.

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.

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:

{
  "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:

{
    "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.