Subscription cancelation with a refund using the REST API

This topic explains how to cancel a subscription with a refund using the REST API by specifying refund and write-off options in the request body.

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.


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.
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.
writeOff	Boolean	Optional; Default is `false`	Indicates whether to write off the outstanding balance on the invoice after refunding. When this field is set to `true` , the generated credit memos have a reason code of `Write-off` and it cannot be overridden.
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.

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 } }

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": [ "A-S00024156" ], "creditMemoNumbers": [ "CM100000169" ], "refunds": [ { "number": "R-00010170", "refundInvoiceNumbers":[ "INV10000001" ], "status": "Success" } ], "writeOff": [ { "invoiceNumber": "INV00056406", "amount": 100.00, "writeOffCreditMemoNumber": "CM100000002", "status": "Success" } ] }`

Response Body

{
    "success": true,
    "orderNumber": "O-00011123",
    "accountNumber": "A%00027753",
    "status": "Completed",
    "subscriptionNumbers": [
        "A-S00024156"
    ],
    "creditMemoNumbers": [
        "CM100000169"
    ],
    "refunds": [
        {
            "number": "R-00010170",
            "refundInvoiceNumbers":[
                "INV10000001"
             ],
            "status": "Success"
        }
    ],
    "writeOff": [
        {
            "invoiceNumber": "INV00056406",
            "amount": 100.00,
            "writeOffCreditMemoNumber": "CM100000002",
            "status": "Success"
        }
    ]
}

The refunds and writeOff fields display refund and write-off results.

Welcome to Zuora Product Documentation

Explore our rich library of product information

Subscription cancelation with a refund using the REST API

zuora-footer