How to place orders via API: new subscriptions, changes and cancellations

Appxite

Introduction

Every order you place through the AppXite Platform API, whether it buys a new Subscription, changes an existing one or cancels it, goes through the same two calls: Create an order (Simplified) saves the order and returns the operations you can run on it, and Execute an order (Simplified) runs the operation to submit it for provisioning. Only the request body changes from one order type to another. This article explains the shared flow and then walks through each order type with a working example for a Microsoft Offer.

Before you start, have the following ready. Retrieving them is out of scope for this article:

  • Your platform URL (sent in the X-Referer header).
  • An Ocp-Apim-Subscription-Key for the Orders product and a valid Bearer token.
  • The Customer organization ID, retrieved with the List all customers API.
  • The OfferId of the product, retrieved with the catalog APIs.
  • The offer's form fields (FormData keys and allowed values), retrieved with the Retrieve a pricing plan for an offer API.
  • For changes to or cancellation of an existing subscription: the SubscriptionId of that subscription, retrieved with the subscription APIs.

In this article

How the order flow works

An order is created first and submitted second. The first call validates the payload and stores the order in Start status; nothing is provisioned yet. The second call runs the operation you choose from the first response, and PlaceOrder moves the order to ProvisionStarted.

  1. Create the order: send the order content. The response returns the order Id and a list of available Operations (for example CreateQuote, ScheduleOrder, SaveForLater, PlaceOrder).
  2. Execute the order: send the order Id, the same order content in OrderCommand, and the operation object from step 1. Most orders use PlaceOrder; orders that take effect on a custom date use ScheduleOrder.
Create an order (Simplified) Execute an order (Simplified)
Method and URL POST https://api.appxite.com/orders/ POST https://api.appxite.com/orders/operation
Platform roles Distributor Admin, Seller Admin, Seller Agent Admin, Account Manager, Customer, Customer Admin Seller Admin, Account Manager
Order status after the call Start ProvisionStarted
NOTE! The two calls allow different roles. A Customer user can create an order, but only a Seller Admin or Account Manager can execute it.

The order type is set by the array you send in the request body. The rest of the flow is the same for every type:

Order type Array in the request body Section
New subscription OrderedOffers Place a new order
Quantity change SubscriptionChanges with ChangeType: SubscriptionChange and OrderScheduleType: Now Change the quantity of a subscription
Scheduled change SubscriptionChanges with OrderScheduleType: OnRenew or Custom and a ScheduledOnDateUtc; Custom is executed with ScheduleOrder Schedule a subscription change
Cancellation CancelOrderItems Cancel a subscription

All calls use the same request headers:

Header Required Value
X-Referer Yes Your platform URL
Ocp-Apim-Subscription-Key Yes Subscription key for the Orders product
Authorization Yes Bearer <token>
Api-Version Yes 3.1
X-On-Behalf-Of Yes Customer organization ID (GUID)
Environment Yes for Create, optional for Execute Sandbox or Production. If omitted, the request goes to Sandbox.
Content-Type Yes application/json
X-ApiUser No Name shown as Created by in the order list
Accept-Language No Locale for translated responses, for example en-US
WARNING! Requests without an Environment header are routed to Sandbox. Set Environment: Production explicitly for live orders.

Place a new order

Use this flow to buy a new subscription. The order content goes in the OrderedOffers array.

Step 1: Create the order

A successful call returns HTTP 200 with the order Id, the order in Start status, and the operations you can run next.

Request body fields

Field Required Description
OrderName Yes Display name of the order.
OrderedOffers[].OfferId Yes ID of the Offer, from the catalog APIs.
OrderedOffers[].OrderItemId Yes A UUID you generate for each order item.
OrderedOffers[].Quantity Yes Quantity ordered. Keep it equal to the quantity key in FormData (for example quantityKey or numberKey).
OrderedOffers[].Name Yes Display name of the order item.
OrderedOffers[].CustomerMarkup No Markup for the Customer. Defaults to 0.0.
OrderedOffers[].FormData Yes The offer's form values. Keys and allowed values come from the Retrieve a pricing plan for an offer API and differ per offer.

Example request (Microsoft Intune Device, 1 license, annual term, monthly billing):

curl --location 'https://api.appxite.com/orders/' \
--header 'X-Referer: <your platform URL>' \
--header 'Ocp-Apim-Subscription-Key: <subscription key>' \
--header 'Authorization: Bearer <token>' \
--header 'Api-Version: 3.1' \
--header 'Environment: Sandbox' \
--header 'X-ApiUser: Postman-API' \
--header 'X-On-Behalf-Of: 9819CF3C-FBD9-4A5C-92E7-3EF5922C36CE' \
--header 'Content-Type: application/json' \
--data '{
    "OrderName": "Microsoft Intune Device ordered",
    "OrderedOffers": [
        {
            "OfferId": "B359AEAC-BF3B-4F19-B4BF-86B4766CF222",
            "OrderItemId": "789dc84f-87a9-4b78-8123-0910c11cab5a",
            "Quantity": 1,
            "CustomerMarkup": 0,
            "Name": "Microsoft Intune Device",
            "FormData": {
                "quantityKey": 1,
                "termDuration": "P1Y",
                "billingCycle": "Monthly",
                "customTermEndDates": "None",
                "transitionEligibilities": "none",
                "tenant": {
                    "DomainName": "testorgd2.onmicrosoft.com",
                    "ExternalId": "d2e1fc1d-30e6-f0b4-cf5b-5f81a9b85f18",
                    "InternalId": "F8B1229F-350A-D94E-E518-C17E1B2CE465"
                }
            }
        }
    ]
}'

Example response (shortened; OrderData echoes the request as a JSON string and is omitted here):

{
    "OrderWithOperations": {
        "Order": {
            "Id": "0e33fea2-7173-4384-bf17-491139c47011",
            "Name": "Microsoft Intune Device ordered",
            "OrderNumber": 90572,
            "ItemsCount": 1,
            "Status": "CommonWorkflow_Start",
            "StatusName": "Start",
            "OrganizationId": "9819cf3c-fbd9-4a5c-92e7-3ef5922c36ce",
            "CreatedByApiUser": "Postman-API",
            "IsEditable": true
        },
        "Operations": [
            {
                "Id": "9e52a7f1-3c48-4d06-b1a7-000000000002",
                "Name": "CreateQuote",
                "Rank": 1
            },
            {
                "Id": "9e52a7f1-3c48-4d06-b1a7-000000000004",
                "Name": "PlaceOrder",
                "RequireValidation": true,
                "RequireTermsAgree": true,
                "RequireUserMessage": false,
                "StartProvision": false,
                "TargetStatusId": "00000000-0000-0000-0000-000000000000",
                "IsTargetStatusEditable": false,
                "Rank": 0
            }
        ]
    },
    "ValidationResult": {
        "OrderedOffersErrors": null,
        "IsValid": true
    },
    "ErrorMessage": null
}

From the response, keep two things for step 2:

  • OrderWithOperations.Order.Id: the order ID.
  • The whole PlaceOrder object from OrderWithOperations.Operations, in particular its Id and TargetStatusId.

The full response also lists ScheduleOrder, Delete, OnlyMarkupChange, SaveForLater and Update. To place the order now, pick PlaceOrder. Find it by Name rather than by its position in the array or its Rank. ScheduleOrder is used for a new purchase that starts on a custom date; that flow is not covered in this article.

Step 2: Execute the order

Send the order ID, the order content, and the PlaceOrder operation from step 1. A successful call returns HTTP 200 with the order in ProvisionStarted status, and provisioning of the Subscription begins.

Request body fields

Field Required Description
OrderId Yes OrderWithOperations.Order.Id from step 1.
OrderCommand Yes The order content: OrderId (same value), OrderName and OrderedOffers, as sent in step 1. Reuse the same OrderItemId values.
Operation Yes The PlaceOrder object from the step 1 Operations array, copied as returned: Id, Name, RequireValidation, RequireTermsAgree, RequireUserMessage, StartProvision, TargetStatusId, IsTargetStatusEditable, Rank.
NOTE! Do not hardcode the operation Id or TargetStatusId. Always take them from the step 1 response for the order you are executing.

Example request

curl --location 'https://api.appxite.com/orders/operation' \
--header 'X-Referer: <your platform URL>' \
--header 'Ocp-Apim-Subscription-Key: <subscription key>' \
--header 'Authorization: Bearer <token>' \
--header 'Api-Version: 3.1' \
--header 'Environment: Sandbox' \
--header 'X-On-Behalf-Of: 9819CF3C-FBD9-4A5C-92E7-3EF5922C36CE' \
--header 'Content-Type: application/json' \
--data '{
    "OrderId": "0e33fea2-7173-4384-bf17-491139c47011",
    "OrderCommand": {
        "OrderId": "0e33fea2-7173-4384-bf17-491139c47011",
        "OrderName": "Microsoft Intune Device ordered",
        "OrderedOffers": [
            {
                "OfferId": "B359AEAC-BF3B-4F19-B4BF-86B4766CF222",
                "OrderItemId": "789dc84f-87a9-4b78-8123-0910c11cab5a",
                "Quantity": 1,
                "CustomerMarkup": 0,
                "Name": "Microsoft Intune Device",
                "FormData": {
                    "quantityKey": 1,
                    "termDuration": "P1Y",
                    "billingCycle": "Monthly",
                    "customTermEndDates": "None",
                    "transitionEligibilities": "none",
                    "tenant": {
                        "DomainName": "testorgd2.onmicrosoft.com",
                        "ExternalId": "d2e1fc1d-30e6-f0b4-cf5b-5f81a9b85f18",
                        "InternalId": "F8B1229F-350A-D94E-E518-C17E1B2CE465"
                    }
                }
            }
        ]
    },
    "Operation": {
        "Id": "9e52a7f1-3c48-4d06-b1a7-000000000004",
        "Name": "PlaceOrder",
        "RequireValidation": true,
        "RequireTermsAgree": true,
        "RequireUserMessage": false,
        "StartProvision": false,
        "TargetStatusId": "00000000-0000-0000-0000-000000000000",
        "IsTargetStatusEditable": false,
        "Rank": 0
    }
}'

Example response (shortened):

{
    "OrderWithOperations": {
        "Order": {
            "Id": "0e33fea2-7173-4384-bf17-491139c47011",
            "Name": "Microsoft Intune Device ordered",
            "ItemsCount": 1,
            "Status": "CommonWorkflow_ProvisionStarted",
            "StatusName": "ProvisionStarted",
            "IsEditable": false
        },
        "Operations": [
            {
                "Id": "9e52a7f1-3c48-4d06-b1a7-000000000013",
                "Name": "Delete",
                "Rank": 4
            }
        ]
    },
    "ValidationResult": {
        "OrderedOffersErrors": null,
        "IsValid": true
    },
    "ErrorMessage": null
}

Check these values to confirm the order was placed:

  • StatusName is ProvisionStarted.
  • IsEditable is false; the order can no longer be changed.
  • ValidationResult.IsValid is true.

To follow the order afterwards, use the Retrieve an order or List all orders API.

Change the quantity of a subscription

Use this flow to raise or lower the quantity of an existing subscription. The two calls are the same as for a new order; the order content goes in the SubscriptionChanges array instead of OrderedOffers, and each item points at the subscription it changes.

Step 1: Create the change order

A successful call returns HTTP 200 with the order Id, the order in Start status, and the operations you can run next, in the same shape as the new order response.

Request body fields

Field Required Description
OrderName Yes Display name of the order.
OrderScheduleType Yes Now applies the change as soon as the order is executed. To apply it later, see Schedule a subscription change.
SubscriptionChanges[].ChangeType Yes SubscriptionChange for a quantity change.
SubscriptionChanges[].SubscriptionId Yes ID of the existing subscription to change.
SubscriptionChanges[].OfferId Yes ID of the subscription's Offer.
SubscriptionChanges[].OrderItemId Yes A UUID you generate for each order item.
SubscriptionChanges[].Quantity Yes The new quantity of the subscription. Keep it equal to the quantity key in FormData.
SubscriptionChanges[].Name Yes Display name of the order item.
SubscriptionChanges[].FormData Yes The offer's form values with the new quantity. Keep the other values as they are on the subscription.

Example request (Microsoft subscription, quantity changed to 8):

curl --location 'https://api.appxite.com/orders/' \
--header 'X-Referer: <your platform URL>' \
--header 'Ocp-Apim-Subscription-Key: <subscription key>' \
--header 'Authorization: Bearer <token>' \
--header 'Api-Version: 3.1' \
--header 'Environment: Sandbox' \
--header 'X-On-Behalf-Of: 9819CF3C-FBD9-4A5C-92E7-3EF5922C36CE' \
--header 'Content-Type: application/json' \
--data '{
    "OrderName": "Quantity change",
    "OrderScheduleType": "Now",
    "SubscriptionChanges": [
        {
            "ChangeType": "SubscriptionChange",
            "SubscriptionId": "84e35b7d-a6fe-b243-2b09-45fe97583ba4",
            "OfferId": "73fb7a23-6eba-463c-9a4d-0158daa213d3",
            "OrderItemId": "b9b46ca1-4d51-46e4-a657-768dafedbe88",
            "Quantity": 8,
            "Name": "Quantity change",
            "FormData": {
                "quantityKey": 8,
                "termDuration": "P1M",
                "billingCycle": "Monthly",
                "customTermEndDates": "None",
                "tenant": {
                    "DomainName": "testorgd2.onmicrosoft.com",
                    "ExternalId": "d2e1fc1d-30e6-f0b4-cf5b-5f81a9b85f18",
                    "InternalId": "F8B1229F-350A-D94E-E518-C17E1B2CE465"
                }
            }
        }
    ]
}'
NOTE! SubscriptionId must hold the ID of an existing subscription of the Customer in X-On-Behalf-Of. An empty value does not identify the subscription to change.

From the response, keep the order Id and the PlaceOrder object for step 2, exactly as for a new order.

Step 2: Execute the change order

Send the order ID, the same SubscriptionChanges content in OrderCommand, and the PlaceOrder operation from step 1. The response has the same shape as the new order execute response; check StatusName and ValidationResult.IsValid the same way.

Request body fields

Field Required Description
OrderId Yes OrderWithOperations.Order.Id from step 1.
OrderCommand Yes The order content: OrderId (same value), OrderName, OrderScheduleType and SubscriptionChanges, as sent in step 1. Reuse the same OrderItemId values.
Operation Yes The PlaceOrder object from the step 1 Operations array, copied as returned.

Example request

curl --location 'https://api.appxite.com/orders/operation' \
--header 'X-Referer: <your platform URL>' \
--header 'Ocp-Apim-Subscription-Key: <subscription key>' \
--header 'Authorization: Bearer <token>' \
--header 'Api-Version: 3.1' \
--header 'Environment: Sandbox' \
--header 'X-On-Behalf-Of: 9819CF3C-FBD9-4A5C-92E7-3EF5922C36CE' \
--header 'Content-Type: application/json' \
--data '{
    "OrderId": "73e8314b-1187-4aed-b251-83caee93da89",
    "OrderCommand": {
        "OrderId": "73e8314b-1187-4aed-b251-83caee93da89",
        "OrderName": "Quantity change",
        "OrderScheduleType": "Now",
        "SubscriptionChanges": [
            {
                "ChangeType": "SubscriptionChange",
                "SubscriptionId": "84e35b7d-a6fe-b243-2b09-45fe97583ba4",
                "OfferId": "73fb7a23-6eba-463c-9a4d-0158daa213d3",
                "OrderItemId": "b9b46ca1-4d51-46e4-a657-768dafedbe88",
                "Quantity": 8,
                "Name": "Quantity change",
                "FormData": {
                    "quantityKey": 8,
                    "termDuration": "P1M",
                    "billingCycle": "Monthly",
                    "customTermEndDates": "None",
                    "tenant": {
                        "DomainName": "testorgd2.onmicrosoft.com",
                        "ExternalId": "d2e1fc1d-30e6-f0b4-cf5b-5f81a9b85f18",
                        "InternalId": "F8B1229F-350A-D94E-E518-C17E1B2CE465"
                    }
                }
            }
        ]
    },
    "Operation": {
        "Id": "694e0c69-e531-4802-a8e5-64e54e8f096d",
        "Name": "PlaceOrder",
        "RequireValidation": true,
        "RequireTermsAgree": true,
        "RequireUserMessage": false,
        "StartProvision": false,
        "TargetStatusId": "f8a95a47-2588-4f0c-ba9c-1bf74ecc346f",
        "IsTargetStatusEditable": false,
        "Rank": 0
    }
}'
NOTE! The operation Id and TargetStatusId in this example differ from the new order example. They depend on the order's workflow, which is another reason to always take them from the step 1 response.

Schedule a subscription change

Use this flow to change a subscription at a later date instead of right away. The calls and the SubscriptionChanges content are the same as for an immediate quantity change. Two top-level fields set when the change takes effect, and the schedule type also decides which operation you execute in step 2:

OrderScheduleType When the change takes effect ScheduledOnDateUtc OfferId Operation in step 2
Now As soon as the order is executed Not sent Sent PlaceOrder
OnRenew At the subscription's next renewal The subscription's renewal date Not sent PlaceOrder
Custom On a date you choose The date the change should take effect Sent ScheduleOrder

ScheduledOnDateUtc is a UTC date and time in the format YYYY-MM-DDThh:mm:ss, for example 2026-11-29T00:00:00.

NOTE! For a custom-date change, execute the ScheduleOrder operation, not PlaceOrder. Both are returned in the step 1 Operations array; find the one you need by Name.

Step 1: Create the scheduled change order

The request body has the same fields as an immediate quantity change, with these differences:

Field Required Description
OrderScheduleType Yes OnRenew or Custom.
ScheduledOnDateUtc Yes For OnRenew, the subscription's renewal date. For Custom, the date the change should take effect.
SubscriptionChanges[].OfferId For Custom only Do not send it for OnRenew; the change applies to the subscription's current Offer. Send it for Custom.

Example request: on renewal (quantity changed to 4 at the next renewal):

curl --location 'https://api.appxite.com/orders/' \
--header 'X-Referer: <your platform URL>' \
--header 'Ocp-Apim-Subscription-Key: <subscription key>' \
--header 'Authorization: Bearer <token>' \
--header 'Api-Version: 3.1' \
--header 'Environment: Sandbox' \
--header 'X-On-Behalf-Of: 9819CF3C-FBD9-4A5C-92E7-3EF5922C36CE' \
--header 'Content-Type: application/json' \
--data '{
    "OrderName": "Scheduled quantity change",
    "OrderScheduleType": "OnRenew",
    "ScheduledOnDateUtc": "2026-11-29T00:00:00",
    "SubscriptionChanges": [
        {
            "ChangeType": "SubscriptionChange",
            "SubscriptionId": "84e35b7d-a6fe-b243-2b09-45fe97583ba4",
            "OrderItemId": "6e946dd4-a894-4066-9633-7dd9a5d089f4",
            "Quantity": 4,
            "Name": "Scheduled quantity change",
            "FormData": {
                "quantityKey": 4,
                "termDuration": "P1M",
                "billingCycle": "Monthly",
                "customTermEndDates": "None",
                "tenant": {
                    "DomainName": "testorgd2.onmicrosoft.com",
                    "ExternalId": "d2e1fc1d-30e6-f0b4-cf5b-5f81a9b85f18",
                    "InternalId": "F8B1229F-350A-D94E-E518-C17E1B2CE465"
                }
            }
        }
    ]
}'

Example request body: on a custom date (same headers as above):

{
    "OrderName": "Scheduled quantity change",
    "OrderScheduleType": "Custom",
    "ScheduledOnDateUtc": "2026-11-15T00:00:00",
    "SubscriptionChanges": [
        {
            "ChangeType": "SubscriptionChange",
            "SubscriptionId": "84e35b7d-a6fe-b243-2b09-45fe97583ba4",
            "OfferId": "73fb7a23-6eba-463c-9a4d-0158daa213d3",
            "OrderItemId": "1bf61c4f-d9c4-405c-9588-9e447ce5a545",
            "Quantity": 4,
            "Name": "Scheduled quantity change",
            "FormData": {
                "quantityKey": 4,
                "termDuration": "P1M",
                "billingCycle": "Monthly",
                "customTermEndDates": "None",
                "tenant": {
                    "DomainName": "testorgd2.onmicrosoft.com",
                    "ExternalId": "d2e1fc1d-30e6-f0b4-cf5b-5f81a9b85f18",
                    "InternalId": "F8B1229F-350A-D94E-E518-C17E1B2CE465"
                }
            }
        }
    ]
}

The response has the same shape as for a new order. Keep the order Id and the operation for step 2: PlaceOrder for OnRenew, ScheduleOrder for Custom.

Step 2: Execute the scheduled change order

Send the order ID, the same content in OrderCommand, including OrderScheduleType and ScheduledOnDateUtc, and the operation from step 1.

Example request: on renewal (with PlaceOrder):

curl --location 'https://api.appxite.com/orders/operation' \
--header 'X-Referer: <your platform URL>' \
--header 'Ocp-Apim-Subscription-Key: <subscription key>' \
--header 'Authorization: Bearer <token>' \
--header 'Api-Version: 3.1' \
--header 'Environment: Sandbox' \
--header 'X-On-Behalf-Of: 9819CF3C-FBD9-4A5C-92E7-3EF5922C36CE' \
--header 'Content-Type: application/json' \
--data '{
    "OrderId": "afb3bdd1-0535-42aa-a455-0d8f299995f4",
    "OrderCommand": {
        "OrderId": "afb3bdd1-0535-42aa-a455-0d8f299995f4",
        "OrderName": "Scheduled quantity change",
        "OrderScheduleType": "OnRenew",
        "ScheduledOnDateUtc": "2026-11-29T00:00:00",
        "SubscriptionChanges": [
            {
                "ChangeType": "SubscriptionChange",
                "SubscriptionId": "84e35b7d-a6fe-b243-2b09-45fe97583ba4",
                "OrderItemId": "6e946dd4-a894-4066-9633-7dd9a5d089f4",
                "Quantity": 4,
                "Name": "Scheduled quantity change",
                "FormData": {
                    "quantityKey": 4,
                    "termDuration": "P1M",
                    "billingCycle": "Monthly",
                    "customTermEndDates": "None",
                    "tenant": {
                        "DomainName": "testorgd2.onmicrosoft.com",
                        "ExternalId": "d2e1fc1d-30e6-f0b4-cf5b-5f81a9b85f18",
                        "InternalId": "F8B1229F-350A-D94E-E518-C17E1B2CE465"
                    }
                }
            }
        ]
    },
    "Operation": {
        "Id": "694e0c69-e531-4802-a8e5-64e54e8f096d",
        "Name": "PlaceOrder",
        "RequireValidation": true,
        "RequireTermsAgree": true,
        "RequireUserMessage": false,
        "StartProvision": false,
        "TargetStatusId": "f8a95a47-2588-4f0c-ba9c-1bf74ecc346f",
        "IsTargetStatusEditable": false,
        "Rank": 0
    }
}'

Example request body: on a custom date (with ScheduleOrder; same headers as above):

{
    "OrderId": "760340e6-1e8b-4f06-aedc-d752af7d4116",
    "OrderCommand": {
        "OrderId": "760340e6-1e8b-4f06-aedc-d752af7d4116",
        "OrderName": "Scheduled quantity change",
        "OrderScheduleType": "Custom",
        "ScheduledOnDateUtc": "2026-11-15T00:00:00",
        "SubscriptionChanges": [
            {
                "ChangeType": "SubscriptionChange",
                "SubscriptionId": "84e35b7d-a6fe-b243-2b09-45fe97583ba4",
                "OfferId": "73fb7a23-6eba-463c-9a4d-0158daa213d3",
                "OrderItemId": "1bf61c4f-d9c4-405c-9588-9e447ce5a545",
                "Quantity": 4,
                "Name": "Scheduled quantity change",
                "FormData": {
                    "quantityKey": 4,
                    "termDuration": "P1M",
                    "billingCycle": "Monthly",
                    "customTermEndDates": "None",
                    "tenant": {
                        "DomainName": "testorgd2.onmicrosoft.com",
                        "ExternalId": "d2e1fc1d-30e6-f0b4-cf5b-5f81a9b85f18",
                        "InternalId": "F8B1229F-350A-D94E-E518-C17E1B2CE465"
                    }
                }
            }
        ]
    },
    "Operation": {
        "Id": "<ScheduleOrder Id from the step 1 response>",
        "Name": "ScheduleOrder",
        "RequireValidation": false,
        "RequireTermsAgree": false,
        "RequireUserMessage": false,
        "StartProvision": false,
        "TargetStatusId": "<ScheduleOrder TargetStatusId from the step 1 response>",
        "IsTargetStatusEditable": false,
        "Rank": 2
    }
}
NOTE! Copy the ScheduleOrder object from your step 1 response as returned. The <...> values in the custom-date example are placeholders for its Id and TargetStatusId.
NOTE! OrderScheduleType and ScheduledOnDateUtc must match between step 1 and step 2. The values in OrderCommand are the ones the order is executed with.

Cancel a subscription

Use this flow to cancel an existing subscription. The two calls are the same as for the other order types; the order content goes in the CancelOrderItems array, and each item points at the subscription it cancels. A cancellation item has no FormData.

Step 1: Create the cancellation order

A successful call returns HTTP 200 with the order Id, the order in Start status, and the operations you can run next, in the same shape as the new order response.

Request body fields

Field Required Description
OrderName Yes Display name of the order.
OrderScheduleType Yes Now cancels the subscription as soon as the order is executed.
CancelOrderItems[].OrderItemId Yes A UUID you generate for each order item.
CancelOrderItems[].SubscriptionId Yes ID of the existing subscription to cancel.
CancelOrderItems[].OfferId Yes ID of the subscription's Offer.
CancelOrderItems[].CanceledOrderItemId No Send null.
CancelOrderItems[].VendorOrderId No Send null.
CancelOrderItems[].CancellationAdditionalInfos No Send null.

Example request (cancel the Microsoft subscription from the previous examples):

curl --location 'https://api.appxite.com/orders/' \
--header 'X-Referer: <your platform URL>' \
--header 'Ocp-Apim-Subscription-Key: <subscription key>' \
--header 'Authorization: Bearer <token>' \
--header 'Api-Version: 3.1' \
--header 'Environment: Sandbox' \
--header 'X-On-Behalf-Of: 9819CF3C-FBD9-4A5C-92E7-3EF5922C36CE' \
--header 'Content-Type: application/json' \
--data '{
    "OrderName": "Subscription cancelled",
    "OrderScheduleType": "Now",
    "CancelOrderItems": [
        {
            "OrderItemId": "8f1e8095-3c50-46cf-ace4-0a2e6c9d79de",
            "CanceledOrderItemId": null,
            "VendorOrderId": null,
            "SubscriptionId": "84e35b7d-a6fe-b243-2b09-45fe97583ba4",
            "CancellationAdditionalInfos": null,
            "OfferId": "73fb7a23-6eba-463c-9a4d-0158daa213d3"
        }
    ]
}'

From the response, keep the order Id and the PlaceOrder object for step 2, exactly as for a new order.

Step 2: Execute the cancellation order

Send the order ID, the same CancelOrderItems content in OrderCommand, and the PlaceOrder operation from step 1. The response has the same shape as the new order execute response; check StatusName and ValidationResult.IsValid the same way.

Request body fields

Field Required Description
OrderId Yes OrderWithOperations.Order.Id from step 1.
OrderCommand Yes The order content: OrderId (same value), OrderName, OrderScheduleType and CancelOrderItems, as sent in step 1. Reuse the same OrderItemId values.
Operation Yes The PlaceOrder object from the step 1 Operations array, copied as returned.

Example request

curl --location 'https://api.appxite.com/orders/operation' \
--header 'X-Referer: <your platform URL>' \
--header 'Ocp-Apim-Subscription-Key: <subscription key>' \
--header 'Authorization: Bearer <token>' \
--header 'Api-Version: 3.1' \
--header 'Environment: Sandbox' \
--header 'X-On-Behalf-Of: 9819CF3C-FBD9-4A5C-92E7-3EF5922C36CE' \
--header 'Content-Type: application/json' \
--data '{
    "OrderId": "47dd145a-2150-4b28-94f1-e7605035c9ed",
    "OrderCommand": {
        "OrderId": "47dd145a-2150-4b28-94f1-e7605035c9ed",
        "OrderName": "Subscription cancelled",
        "OrderScheduleType": "Now",
        "CancelOrderItems": [
            {
                "OrderItemId": "8f1e8095-3c50-46cf-ace4-0a2e6c9d79de",
                "CanceledOrderItemId": null,
                "VendorOrderId": null,
                "SubscriptionId": "84e35b7d-a6fe-b243-2b09-45fe97583ba4",
                "CancellationAdditionalInfos": null,
                "OfferId": "73fb7a23-6eba-463c-9a4d-0158daa213d3"
            }
        ]
    },
    "Operation": {
        "Id": "6fe39b9a-786d-44b7-a39e-c9e8c6edc9a2",
        "Name": "PlaceOrder",
        "RequireValidation": true,
        "RequireTermsAgree": true,
        "RequireUserMessage": false,
        "StartProvision": false,
        "TargetStatusId": "2ec57053-9d34-4a0a-bee9-9378f6289ae3",
        "IsTargetStatusEditable": false,
        "Rank": 0
    }
}'
WARNING! Once the cancellation order is executed, the subscription is cancelled with the vendor. Check SubscriptionId before you execute, and test the flow with Environment: Sandbox first.

Troubleshooting

422 Unprocessable Entity: FormDataValidationError

The platform validates FormData against the offer's form definition on both calls, for new orders and subscription changes alike. If a key is missing, misspelled, or belongs to a different offer, the call returns 422 Unprocessable Entity, OrderWithOperations is null, and no order is created or executed.

In the example below, a body built for a Microsoft 365 license was sent for the Dynamics 365 Commerce offer. That offer expects different form controls:

{
    "OrderWithOperations": null,
    "ValidationResult": {
        "OrderedOffersErrors": [
            {
                "OrderItemIndex": 0,
                "OrderItemType": "OrderedOffers",
                "OrderItemName": "Dynamics 365 Commerce",
                "FormDataErrors": {
                    "Tenant": "The control is required.",
                    "quantityBox1": "The control is required.",
                    "quantityKey": "No such control in the form definition.",
                    "termDuration": "No such control in the form definition.",
                    "billingCycle": "No such control in the form definition.",
                    "customTermEndDates": "No such control in the form definition.",
                    "transitionEligibilities": "No such control in the form definition."
                },
                "ErrorMessage": "FormDataValidationError"
            }
        ],
        "IsValid": false
    },
    "ErrorMessage": null
}

How to read the error:

Field or message Meaning Fix
OrderedOffersErrors / SubscriptionChangesErrors Errors for new order items or for subscription change items. Look in the array that matches the order type you sent.
OrderItemIndex Zero-based position of the failing item in that array. Go to that item in your request body.
The control is required. The offer's form requires this key and the request did not send it. Add the key with a valid value.
No such control in the form definition. The request sent a key this offer's form does not have. Remove the key.
IsValid: false At least one item failed validation. Fix every item listed in the error arrays, then resend.

To prevent this error:

  • Build FormData for each offer from its own Retrieve a pricing plan for an offer response. Do not reuse a body from another offer, even one from the same vendor.
  • Copy key names exactly as the form definition returns them. In the example, this offer expects Tenant and quantityBox1, while the Microsoft Intune offer expects tenant and quantityKey.
  • Keep Quantity equal to the value of the offer's quantity key.
NOTE! Because PlaceOrder has RequireValidation: true, the same check runs again on execute. Send the same OrderedOffers or SubscriptionChanges in OrderCommand that passed in step 1.

Other issues

Symptom Likely cause Fix
Request body fails to parse Malformed JSON, such as a missing comma, quote or bracket Check the body in a JSON validator and fix the reported position.
Order created in Sandbox instead of Production Environment header missing Send Environment: Production.
Request is rejected as unauthorized Authorization header missing or the token has expired Send Authorization: Bearer <token> with a valid token on both calls.
Execute call is rejected for your user The user's role cannot execute orders Use a Seller Admin or Account Manager account.
Order not found or not executable OrderId or operation Id copied from a different order Take both from the step 1 response for this order.
Subscription change is rejected SubscriptionId empty, or it belongs to another Customer Send the ID of an existing subscription of the Customer in X-On-Behalf-Of.
Custom-date change is not scheduled as expected PlaceOrder executed instead of ScheduleOrder Execute the ScheduleOrder operation from the step 1 response.
Scheduled change is rejected or applied at the wrong time ScheduledOnDateUtc missing or in the wrong format, or different values in step 1 and OrderCommand Send a UTC date as YYYY-MM-DDThh:mm:ss, with the same OrderScheduleType and ScheduledOnDateUtc in both calls.

Summary

Every order on the AppXite Platform API, whether it creates a new Subscription, changes an existing one, or cancels it, follows the same two-step flow. First, you send the order content to Create an order (Simplified), which validates the payload and stores the order in Start status. Then you send the order ID, the same content, and the operation object from the first response to Execute an order (Simplified), which submits the order for provisioning. The order type is determined by the array in the request body: OrderedOffers for a new purchase, SubscriptionChanges for a quantity or scheduled change, and CancelOrderItems for a cancellation.

Most orders are executed with the PlaceOrder operation, including immediate changes and on-renewal changes. Custom-date changes use the ScheduleOrder operation instead. In both cases, the operation Id and TargetStatusId must come from the step 1 response for the specific order being executed, and the FormData must match the form definition of the Offer as returned by the Retrieve a pricing plan for an offer API. A successful execute response returns StatusName as ProvisionStarted and ValidationResult.IsValid as true, confirming that the order has been submitted.

Was this article helpful?

0 out of 0 found this helpful

Add comment

Please sign in to leave a comment.