1. Orders integration

Work with the Orders Entity Views and Actions API (C#)

Version:

External systems can exchange order-related information using the Orders Entity Views and Actions API.

Note

The Views and Actions API is an authoring API designed to service a business user interface and is not optimized for integration scenario.

You should consider the following when using the Views and Actions API for your commerce integration:

  • The Views and Actions API can only process one Commerce entity at the time and does not support batch processing.

  • The Views and Actions API carries more overhead than the Commerce web service API. A call to the Views and Action API is typically a 3-step process that requires getting the action's view, modifying the view's properties with updated values, and then executing the action.

As shown in this example, calls to the Orders Views and Actions API typically include the following steps: 

  • Getting the action's view. 

  • Modifying the view's properties values (as required).

  • Executing the action.

Note

For any API calls to the XC Commerce Engine, you must:

Work with Orders using the Entity Views and Actions API (C#)

You can use the Entity Views and Actions API to perform the following orders-related operations:

Put an order on hold (C#)

You can only put an order on hold when the order status is pending.

To put an order on hold using C#:

  1. Get the entity view for the action, for example:

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-Order-{orderId}", string.Empty, "HoldOrder",
string.Empty);
EntityView view = Proxy.GetValue(query);

  2. Execute the action:

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

Delete an order line (C#)

You can delete an order line when the order status is pending.

To delete a line from a pending order using C#:

  1. Get the entity view for the action, for example: 

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-Order-{orderId}", string.Empty, "DeleteLineItem", lineId);

  2. Execute the action: 

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

Add an order line (C#)

You can only add a line to an order when the status of the order is on hold.

To add a line item to a pending order using C#:

  1. Get the entity view (the request must specify the order ID), for example:

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-Order-{orderId}", "AddLineItem",
"AddLineItem", string.Empty)
EntityView view = Proxy.GetValue(query);

  2. Specify the line item property and the quantity, for example:

    var itemProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("Item"));
itemProperty.Value = "Adventure Works Catalog|AW188-06|20";
var quantityProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("Quantity"));
quantityProperty.Value = "1";

  3. Execute the action:

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

Edit an order line (C#)

You can only edit an order line when the status of the order is on hold.

To modify an order line, for example, change a line item quantity to 5:

  1. Get the entity view for the action for a given order (the request must specify the order ID and the line item ID), for example:

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-Order-{orderId}", "EditLineItem",
"EditLineItem", lineId);
EntityView view = Proxy.GetValue(query);

  2. Modify the quantity of the line item to 5  :

    var quantityProperty = view.Properties.FirstOrDefault(p =>; p.Name.Equals("Quantity")); quantityProperty.Value = "5";

  3. Execute the action:

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));

Release an order from hold (C#)

To release an order from the on hold status:

  1. Get the entity view for the action, for example:

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-Order-{orderId}", string.Empty, "ReleaseOrder",
string.Empty);
EntityView view = Proxy.GetValue(query);

  2. Execute the action: 

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));
    Note

    After it has been released, the order returns to the pending status. 

Undo changes made to an order (C#)

To undo changes made to an order (while it was on hold):

  1. Get the entity view for the action, for example:

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-Order-{orderId}", string.Empty, "UndoOnHoldOrder", string.Empty); EntityView view = Proxy.GetValue(query);

  2. Execute the action:

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));
    Note

    After you undo the changes, the order remains on hold.

Cancel hold on an order (C#)

To cancel the hold on an order using C#:

  1. Get the entity view for the action, for example:

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-Order-{orderId}", string.Empty, "CancelOnHoldOrder", string.Empty);
EntityView view = Proxy.GetValue(query);

  2. Execute the action:

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));
Note

After you cancel the hold, the order returns to the Pending status.

Cancel an order (C#)

You can only cancel orders that are in the pending status.

To cancel a pending order using C#:

  1. Get the entity view for the action, for example:

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-Order-{orderId}", string.Empty, "CancelOrder",
string.Empty);
EntityView view = Proxy.GetValue(query);

  2. Execute the action:

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));
    Note

    After you cancel the hold, the order status changes to cancelled.

Return an item (C#)

You can perform a return merchandise authorization (RMA) request programmatically using the Entity Views and Actions API.

Note

You can request an RMA when an order status is completed.

To perform a RMA request on an order line item using C#:

  1. Specify the reason for returning the item, as well as the quantity of this line item to return.  In the following example, the reason for returning is wrong Item. The quantity returned is 1.

    DataServiceQuerySingle<EntityView> query = container.GetEntityView($"Entity-Order-{orderId}", "RequestRma", "ValidateRmaRequest", lineId);
EntityView view = Proxy.GetValue(query);
var reasonProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("Option"));
var availableReasonsPolicy = reasonProperty.Policies.OfType<AvailableSelectionsPolicy>().FirstOrDefault();
reasonProperty.Value = availableReasonsPolicy?.List.FirstOrDefault(o => o.Name.Equals("WrongItem")).Name;
view.Properties.FirstOrDefault(p => p.Name.Equals("Quantity")).Value = 1;

  2. Confirm to proceed with the return request.

    CommerceCommand command = Proxy.DoCommand(container.DoAction(view));
view = command.Models.OfType<EntityView>().FirstOrDefault(v => v.Name.Equals(view.Name));
var countryProperty = view.Properties.FirstOrDefault(p => p.Name.Equals("Country"));
countProperty.Value = "3";
var availableCountryPolicy = optionProperty.Policies.OfType<AvailableSelectionsPolicy>().FirstOrDefault();
countryProperty.Value = availableCountryPolicy?.List.FirstOrDefault(o => o.Name.Equals("CA")).Name;
command = Proxy.DoCommand(container.DoAction(view));
view = command.Models.OfType<EntityView>().FirstOrDefault(v => v.Name.Equals(view.Name));
command = Proxy.DoCommand(container.DoAction(view));

  3. Execute the action:

    view = command.Models.OfType<EntityView>().FirstOrDefault(v => v.Name.Equals(view.Name));
command = Proxy.DoCommand(container.DoAction(view));command = Proxy.DoCommand(container.DoAction(view));
If you have suggestions for improving this article, let us know!