In the previous post, we’ve created the Order & OrderSummary by using Salesforce API and Salesforce Order Management core action. Now, let’s execute one of the other main core actions of the Salesforce Order Management; Cancel Items action.
All Salesforce Order Management core actions are listed under ConnectAPI namespace. Some actions are under OrderSummary class, some are under others such as FulfillmentOrder or Routing class or OrderSummaryCreation class which we used in the previous post to create OrderSummary record.
We’ll be using ConnectAPI.OrderSummary class for canceling items.
What does Cancel Items action do?
As you can guess, the Cancel Items action cancels the item which is the Order Item Summary record, not Order Item.
The action gets Order Item Summary Id and the Quantity as input (and a few more) which cancels the specific item quantity as given Quantity.
The Cancel Items action also supports fees.
Why use ConnectAPI and not DML?
Once there is an Order Summary record tied to an Order, Salesforce doesn’t allow us to modify Order directly. So, as an API we use Connect API which applies the change to both summary and original records which are Order Item Summary & Order Summary / Order Item & Order.
When to use Cancel Items action?
In order to understand better, let’s see the Order Management Lifecycle.
Think about the business process where we should cancel the items or until which point we should cancel items? The answer should be before shipping the order because once we ship the items, we shouldn’t cancel the items but return them.
So that means we can cancel the items in the Pre-fulfillment stage which means having no allocation for the order items or you can cancel the items in the In-fulfillment stage which means the order items are allocated and maybe even packed but not shipped. Because once the items are shipped, it should be considered as return not cancellation.
For now, I’ll talk about the Pre-fulfillment stage. The In-fulfillment stage will be discussed once we create Fulfillment Order records.
How to use Cancel Items action?
Prerequisites
Before using the Cancel Items action, there is one prerequisite we need to accomplish. I know when you consider the business rules, there should be many rules but Salesforce Order Management cares about only one field of the Order Item Summary record that will be cancelled; QuantityAvailableToCancel. Of course, I’m not considering the order life cycle type of the Order Summary which should be Managed.
QuantityAvailableToCancel is a formula field and the formula is:QuantityOrdered - (QuantityCanceled and QuantityAllocated)
QuantityOrdered standard field represents the quantity of the Order Item record.
QuantityCanceled standard field represents the quantity canceled of the Order Item record.
QuantityAllocated standard field represents the quantity allocation which means the Order Item Summary records has a related Fulfillment Order Line Item record.
Usage
Before Using Cancel Item
First, I’d like to talk about Cancel Item flow which is provided by Salesforce as template flow, ready to use. That is, a flow becomes enabled once Salesforce Order Management is enabled. Cancel Item flow is a screen flow built for service agents.
Let’s see the Order Item Summaries’ statuses before using Cancel Items action.
The status of the Order Item Summary records’ is Ordered which means the Order Items are as they are.
Using Cancel Item (with a flow)
Now let’s execute the Cancel Items flow and cancel items.
The first screen is the product selection screen. By the default, flow has a filter for Order Item Summary records which is QuantityAvailableToCancel > 0. If there are no products available to cancel, the flow will end here. Also, the shipping items (Type = Delivery Charge) won’t be listed here.
The second screen is the screen where we select the quantity & reason for the cancel process. There is also another option called Remove shipping amount which removes the shipping amount from the Order Item record(s). If you want to select a different reason than the default, navigate to Order Item Summary Change object & Reason field which is a picklist and holds reasons for the cancellation process.
The third screen is the screen where we review our selections and the outcome of the cancellation process. This process is actually another action of the OrderSummary ConnectAPI class called Preview Cancel.
Submit button will apply the cancellation to the Order Item records.
And as the last, we the message from the flow.
Now, let’s see the Order Summary record.
After Using Cancel Item
I used the first Order Item Summary record (Product 1) for the cancellation process and as you can see the quantity has dropped to 2 from 5 because I cancelled 3 of them. Also the Line Total column has been dropped to 20 from 50 since Unit Price is 10.
Now, you might wonder if behind the scenes a Change Order record has been created for the Order Summary because as you remember, what we said about Change Orders is that “represents a change to an order that affects charges and payments, such as canceling or returning a product from an order. A Change Order object updates the corresponding Order Summary object”.
Since a Change Order is basically an Order, let’s query for the Orders and see if we have the Change Order record.
As you can see we have an additional Order which is a Change Order because it has relation with the original Order record. That is the relation chains the Change Order records to the original Order record.
Also, the same thing happens to the Order Items which are Change Order Item records.
As you can see, the first two Order Item records belong to the Change Order record.
Using Cancel Item (with Apex)
// represents the Order Item Summary record
ConnectApi.ChangeItemInputRepresentation changeItemInput = new ConnectApi.ChangeItemInputRepresentation();
changeItemInput.orderItemSummaryId = '10u3L0000003OhUQAU';
changeItemInput.quantity = 2;
changeItemInput.reason = 'Unknown';
changeItemInput.shippingReductionFlag = true;
// represents the main input
ConnectApi.ChangeInputRepresentation changeInput = new ConnectApi.ChangeInputRepresentation();
changeInput.changeItems = new List<ConnectApi.ChangeItemInputRepresentation>
{
changeItemInput
};
// execution, the first param is the Id of the Order Summary record
ConnectApi.SubmitCancelOutputRepresentation output = ConnectAPI.OrderSummary.submitCancel('1Os3L0000001GBjSAM', changeInput);If you have multiple Order Item Summary records to cancel, then loop and add to a list. Now let’s see the Order Summary.
As you can see, the Quantity is zero, Line Total is zero and the Status is Canceled. Since I flagged shippingReductionFlag as true for both processes, the shipping Order Item record’s Line Total has decreased.
Finally, if you want review cancellation outcome before the cancel process, all you need to do is execute ConnectAPI.OrderSummary.previewCancel method which takes the same input as ConnectAPI.OrderSummary.submitCancel.
Other Ways to Cancel Items
Flow Core Actions
Connect REST APIs
For the official document, see Salesforce Order Management Cancel an Order Item