Cancel software purchases

Article
11/10/2023

You can use the Partner Center APIs to cancel software subscriptions and perpetual software purchases (as long as those purchases were made within the cancellation window from the purchase date). You don't need to create a support ticket to make such cancellations, and can use the following self-service methods instead.

You can also cancel software subscriptions (not including perpetual software) by using the Update a subscription by ID API.

Prerequisites

Credentials as described in Partner Center authentication. This scenario supports authentication with both standalone App and App+User credentials.

C#

To cancel a software order,

Pass your account credentials to the CreatePartnerOperations method to get an IPartner interface to get partner operations.
Select a particular Order you wish to cancel. Call the Customers.ById() method with the customer identifier, followed by Orders.ById() with order identifier.
Call the Get or GetAsync method to retrieve the order.
Set the Order.Status property to cancelled.
(Optional) If you want to specify certain line items for cancellation, set the Order.LineItems to list of line items that you want to cancel.
Use the Patch() method to update the order.

// IPartnerCredentials accountCredentials;
// string customerTenantId;

IPartner accountPartnerOperations = PartnerService.Instance.CreatePartnerOperations(accountCredentials);

// Cancel order
var order = accountPartnerOperations.Customers.ById(customerTenantId).Orders.ById(orderId).Get();
order.Status = "cancelled";
order.LineItems = new List<OrderLineItem> {
    order.LineItems.First()
};
order = accountPartnerOperations.Customers.ById(customerTenantId).Orders.ById(orderId).Patch(order);

REST request

Request syntax

Method	Request URI
PATCH	{baseURL}/v1/customers/{customer-tenant-id}/orders/{order-id} HTTP/1.1

URI parameters

Use the following query parameters to cancel a software order.

Name	Type	Required	Description
customer-tenant-id	guid	Y	The value is a GUID formatted customer tenant identifier that allows the reseller to filter the results for a given customer that belongs to the reseller.
order-id	string	Y	The value is a string that denotes the identifier of the order that you want to cancel.

Request headers

For more information, see Partner Center REST headers.

Request body

{
    "id": "c403d91b21d2",
    status": "cancelled",
    "lineItems": [
        {
            "lineItemNumber": 0,
            "offerId": "DG7GMGF0FKZV:0003:DG7GMGF0DWMS"
        }
    ]
}

Request example

PATCH https://api.partnercenter.microsoft.com/v1/customers/<customer-tenant-id>/orders/<order-id> HTTP/1.1
Accept: application/json
MS-RequestId: 655890ba-4d2b-4d09-a95f-4ea1348686a5
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd

{
    "id": "c403d91b21d2",
    "status": "cancelled",
    "lineItems": [
        {
            "lineItemNumber": 0,
            "offerId": "DG7GMGF0FKZV:0003:DG7GMGF0DWMS"
        }
    ]
}

REST response

If successful, this method returns the order with cancelled line items.

The order status will be marked as either cancelled if all the line items in the order are cancelled, or completed if not all line items in the order are cancelled.

Response success and error codes

Each response comes with an HTTP status code that indicates success or failure and other debugging information. Use a network trace tool to read this code, error type, and parameters. For the full list, see Partner Center REST error codes.

Response example

In the following example response, you can see that the quantity of line item has become zero (0). This change means that the line item that was marked for cancellation has been cancelled successfully. The example order contains other line items that weren't cancelled, which means that the status of the overall order will be marked as completed, not cancelled.

HTTP/1.1 200 OK
Content-Length: 866
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: 655890ba-4d2b-4d09-a95f-4ea1348686a5

{
    "id": "c403d91b21d2",
    "alternateId": "c403d91b21d2",
    "referenceCustomerId": "45411344-b09d-47e7-9653-542006bf9766",
    "billingCycle": "one_time",
    "currencyCode": "USD",
    "currencySymbol": "$",
    "lineItems": [
        {
            "lineItemNumber": 0,
            "offerId": "DG7GMGF0FKZV:0003:DG7GMGF0DWMS",
            "termDuration": "P3Y",
            "transactionType": "New",
            "friendlyName": "SQL Server Enterprise - 2 Core License Pack - 3 year",
            "quantity": 0,
            "links": {
                "product": {
                    "uri": "/products/DG7GMGF0FKZV?country=US",
                    "method": "GET",
                    "headers": []
                },
                "sku": {
                    "uri": "/products/DG7GMGF0FKZV/skus/0003?country=US",
                    "method": "GET",
                    "headers": []
                },
                "availability": {
                    "uri": "/products/DG7GMGF0FKZV/skus/0003/availabilities/DG7GMGF0DWMS?country=US",
                    "method": "GET",
                    "headers": []
                }
            }
        },
        {
            "lineItemNumber": 1,
            "offerId": "DG7GMGF0DVT7:000C:DG7GMGF0FVZM",
            "termDuration": "P3Y",
            "transactionType": "New",
            "friendlyName": "Windows Server CAL - 1 Device CAL - 3 year",
            "quantity": 1,
            "links": {
                "product": {
                    "uri": "/products/DG7GMGF0DVT7?country=US",
                    "method": "GET",
                    "headers": []
                },
                "sku": {
                    "uri": "/products/DG7GMGF0DVT7/skus/000C?country=US",
                    "method": "GET",
                    "headers": []
                },
                "availability": {
                    "uri": "/products/DG7GMGF0DVT7/skus/000C/availabilities/DG7GMGF0FVZM?country=US",
                    "method": "GET",
                    "headers": []
                }
            }
        }
    ],
    "creationDate": "2019-12-12T17:33:56.1306495Z",
    "status": "completed",
    "transactionType": "UserPurchase",
    "links": {
        "self": {
            "uri": "/customers/45411344-b09d-47e7-9653-542006bf9766/orders/c403d91b21d2",
            "method": "GET",
            "headers": []
        },
        "provisioningStatus": {
            "uri": "/customers/45411344-b09d-47e7-9653-542006bf9766/orders/c403d91b21d2/provisioningstatus",
            "method": "GET",
            "headers": []
        },
        "patchOperation": {
            "uri": "/customers/45411344-b09d-47e7-9653-542006bf9766/orders/c403d91b21d2",
            "method": "PATCH",
            "headers": []
        }
    },
    "client": {
        "marketplaceCountry": "US",
        "deviceFamily": "UniversalStore-PartnerCenter",
        "name": "Partner Center API"
    },
    "attributes": {
        "objectType": "Order"
    }
}

Share via