Next-generation platform

Implementing order modification

As a store associate, you can use the order modification feature in the Sterling Store Engagement to add a new product to or remove a product from the order, edit product quantity, modify delivery methods, and capture appropriate payment details for the change in the order total of an existing order. This section describes the APIs, services, and other components that are used to implement the order modification feature.

Limitations

  • You must have all the required resource permissions, including ISF000058, to be able to modify orders and order lines.
  • Order modification is supported only for sales orders.
  • Modification of carry lines is not supported.
  • Order modification is disabled in case of any of the following conditions:
    • MaxOrderStatus is greater than or equal to 3700 (Order shipped).
    • Order contains only carry lines.
    • Order is locked by another user. That is, if the order has any pending changes (HasPendingChanges = 'Y') and currentLoginId is not equal to PendingChangesUserID.

Modifying an order by using the Edit button on the Order summary page

Clicking the Edit button in the Order summary page opens the Edit order page. You can modify the order as well as the order line. For more information about the actions you can perform during order modification, see Order modification.

Any modifications made to a confirmed order remain in a pending state until the user saves or rolls back the changes, or the changes automatically expire after a preconfigured time frame, which is defined in the Applications Manager. After the specified time, the pending changes automatically expires and the order rolls back to its original state.

The getCompleteOrderDetails API is called to retrieve the order and order line details such as the order total, coupons applied, and so on.

Adding a new product to an existing order

  • You must have the ISF000059 resource permission to add order lines to an existing order.
  • If the current date is past the order age, you cannot add a new product to the order. The WSC_ORDER_AGE rule is used to fetch the maximum order age. However, other modifications such as applying coupons or changing the delivery method can be done.
  • If the product is added to the order by scanning and if sufficient quantity is available, the getCompleteItemList API is called to add the product to the order with the default quantity as 1 and the delivery method as SHIP. If the product is not available, you are redirected to the Product details page.
  • If you are searching for the product to be added to the order by using keywords, the Product search results page opens with the list of products that match the search keywords. You can select the product that you want to add to the order from these results.
  • The modifyFulfillmentOptions API is called to add a new order line and to add a note with the YCD_MULTI_ADD_LINES_INFO reason code.
  • Changes made to the order are committed to the database only when you click Save, which will trigger the changeOrder API.
  • If the changes are successfully saved to the order, the getCompleteOrderDetails API is called to refresh the page and display a success message. After that, you can proceed to update the payment details.
  • You cannot add carry order lines to the order by modifying the order.
  • You can only add regular and variant items.
  • The following order modification rules must be enabled at order level by using Applications Manager:
    • ADD_LINE
    • ADD_NOTE
  • The following APIs are invoked to add a new product to an existing order:
    • getRuleDetails. To fetch the maximum order age from the WSC_ORDER_AGE rule.
    • getCompleteItemList. To retrieve the product details.
    • modifyFulfillmentOptions. To add a product to the order.
    • getCompleteOrderDetails. To refresh the page with a message displaying the updated order total and the amount due or refund amount.
    • changeOrder. To save the changes made to the order.

Removing an order line from an existing order

  • You must have the ISF000060 resource permission to remove an order line from an existing order.
  • Cancellation of order lines is enabled only if MaxLineStatus < 3700 (Shipped) and not equal to 1100.7777 (CARRIED).
  • If the customer decides to cancel one or more products in an order, you can click the Remove button for the corresponding order line.

    A confirmation window is displayed where you can select the reason for cancellation and confirm. The modifyFulfillmentOptions API is called to remove the product.

  • On canceling the order line, a note is added with YCD_CANCEL_INFO reason code.
  • After cancellation, you can only view the notes that were added to the canceled lines and cannot perform any other actions.
  • If the order line is newly added, then you only have to confirm to remove the product from the order. No cancellation reason is required. The changeOrder API is used to remove newly added products to the order.
  • On saving, the changeOrder API is called to apply the changes to the order.
  • The following order modification rules must be enabled by using Applications Manager:
    • CANCEL
    • ADD_NOTE at the order level for getting the canceled order status.
  • The following APIs are invoked to remove an order line from an existing order:
    • getCommonCodeList with CodeType as YCD_CANCEL_REASON. To display the cancellation reasons.
    • modifyFulfillmentOptions with Action="CANCEL". To cancel the order line in pending changes mode.
    • changeOrder with Action="REMOVE". To cancel the new order lines in pending changes mode.
    • changeOrder. To commit the changes to the database.

Editing the order line quantity

  • The ISF000049 resource permission is required to update the order line quantity.
  • You can update the order line quantity only if the following conditions are met:
    • MaxLineStatus < 3700 (Shipped) and MaxLineStatus is not equal to 1100.7777 (CARRIED)
    • DeliveryMethod is not equal to DEL.
  • You can either increase or decrease the quantity of an order line as per the requirement of the customer.
  • If you reduce the ordered quantity, it is validated against the AvailableQtyForCancelAndStopDelivery attribute.
  • When the order line quantity is changed, the getItemAvailabilityForStore API is invoked.
  • If the required inventory is available, the modifyFulfillmentOptions API is called in the pending changes mode to update the entered quantity.
  • The getCompleteOrderDetails API is called to refresh the page with a message displaying the updated order total and the amount due or refund details. On clicking Save, the changeOrder API is called to save the changes to the order.
  • The following order modification rules must be enabled by using Applications Manager:
    • ADD_QUANTITY
    • ADD_NOTE at the order level for getting the current order status.
  • The following APIs are invoked to edit the order line quantity:
    • getItemAvailabilityForStore. To retrieve the real-time availability of the product for the updated quantity.
    • modifyFulfillmentOptions. To update the edited quantity.
    • getCompleteOrderDetails. To refresh the page with a message displaying the updated order total and the amount due or refund for the order.
    • changeOrder. To commit the changes to the database.

Replacing a product in the order with its variant

From the Edit order page, you can click the product description link to open the Product details page. You can view the variants for the product and add it to the cart.

You can then remove the previously added variant from the order if it is not required.

The following APIs are called to replace a product in the order with its variant:
  • getRuleDetails. To fetch the maximum order age from the WSC_ORDER_AGE rule.
  • modifyFulfillmentOptions. To update the variation product.
  • changeOrder. To commit the changes to the database.

Modifying the delivery methods

  • The ISF000061 resource permission is required to modify the delivery method for an order line.
  • The Edit delivery method option is not available if the order line delivery method is CARRY, is Canceled, or is equal to DEL (Delivery line).
  • You can modify the delivery method of an order line by clicking Edit delivery method. The Edit delivery method window is displayed with two tabs, Ship and Pick up. By default, the Edit delivery method window displays the tab corresponding to the current delivery method of the order line.
  • When the delivery method of an order line is changed from pick up to ship, the modifyFulfillmentOptions API is called to set the DeliveryMethod attribute to SHP and the CarrierServiceCode attribute based on the selected carrier service option, if applicable.

    The getCarrierServiceOptionsForOrdering API is called to retrieve the list of carrier services in the Ship tab. The modifyFulfillmentOptions API also sets the shipping address for the order line, if the order does not already have a shipping address.

  • When the delivery method of a product is changed from ship to pick up, the modifyFulfillmentOptions API is called to set the DeliveryMethod attribute to PICK and the ShipNode attribute to the selected store. The logic implemented to select or change a store is applicable.

    The modifyFulfillmentOptions API is called in the pending changes mode provided there are no existing pending changes and the status of the order line is less than Scheduled.

    If the status of the order line is Scheduled (MaxLineStatus >= '1500' ) or beyond and the Allow Modifications of Orders Beyond Scheduled Status rule (WSC_ALLOW_ORDER_MODIFICATION_POST_RELEASE) is enabled in Sterling Business Center, the pending changes are committed. The orderline is unscheduled upon confirmation.

    Similarly, if a shipment is created for the order line, the order line is removed from the shipment before you can proceed to make any changes.

  • The getCompleteOrderDetails API is called to refresh the page with the new delivery method.
  • On clicking Save, the changeOrder API is called to save the changes to the order.
  • The CHANGE_DELIVERY_METHOD order modification rule must be enabled by using Applications Manager
  • The following APIs are invoked to modify the delivery methods:
    • modifyFulfillmentOptions. To update the existing order line delivery method in the order.
    • changeOrder. To update the new line delivery method on order.
    • getCarrierServiceOptionsForOrdering. To retrieve the list of carrier services to display in the Ship tab.
    • getRuleDetails. To fetch whether order modifications are allowed beyond scheduled status from the WSC_ALLOW_ORDER_MODIFICATION_POST_RELEASE rule.
    • getCompleteOrderDetails. To refresh the page with the new delivery method.
    • changeOrder. To commit the changes to the database.

Adding, modifying, and removing charges and overriding price in order lines

The ISF000050 (Add or modify order line charges) and ISF000045 (Price override) resource permissions are required to modify the delivery method for an order line.

Viewing and modifying charges - as a store associate, you can view and modify charges for products by clicking the item total link for each order line.

  • The getCompleteOrderDetails API is called to display the list of charges applied on the order line.
  • You must have the required permissions to add and modify order line charges for adding or modifying the charges that are currently applied.
  • Only charges that are manually applied are editable. Charges that are generated automatically by the pricing engine are displayed as read only.
  • You can modify the charges only if the order line status is less than Included in shipment or is not Carried, and the order line delivery method is not equal to DEL (Delivery line).
  • Notes that are entered while adding or modifying charges are saved in the order or order line with YCD_ADD_MODIFY_CHARGES as the reason code.
  • You can override the price only for products in existing order lines.
  • The following order modification rules must be enabled by using Applications Manager:
    • PRICE
    • ADD_NOTE at the order line level for getting the current order line status.
  • The following APIs are invoked to modify the charges in order lines:
    • getChargeCategoryList. To retrieve the list of charge categories.
    • getChargeNameList. To retrieve the list of charge names.
    • changeOrder. To apply the charge modifications.
    • getCompleteOrderDetails. To display the list of charges applied on the order line.

Adding, modifying, and removing charges in orders

You can view and modify the charges for all the products in the order by clicking Order total.

  • The ISF000051 (Add or modify order header charges) resource permission is required to modify the charges in orders.
  • The getCompleteOrderDetails API is called to display the list of charges applied on the order.
  • You must have the required permissions to add and modify order header charges for adding or modifying the charges that are currently applied.
  • Only charges that are manually applied are editable. Charges that are generated automatically by the pricing engine are displayed as read only.
  • You can modify the charges only if the order status is less than Included in shipment or is not Carried.
  • Notes that are entered while adding or modifying charges are saved in the order or order line with YCD_ADD_MODIFY_CHARGES as the reason code.
  • The following order modification rules must be enabled by using Applications Manager:
    • PRICE
    • ADD_NOTE at the order level for getting the current order status.
  • The following APIs are invoked to modify the charges in orders:
    • getChargeCategoryList. To retrieve the list of charge categories.
    • getChargeNameList. To retrieve the list of charge names.
    • changeOrder. To apply the charge modifications.
    • getCompleteOrderDetails. To display the list of charges applied on the order.

Applying and removing coupons

  • The ISF000052 resource permission is required to update promotions or coupons.
  • You can add a new coupon to an existing order by clicking Edit and clicking Coupons applied. You can then scan or enter a promotion code in the Apply coupons window. The translateBarCode API is called followed by the changeOrder API to apply the promotion.
  • You can also remove an applied coupon, which calls the changeOrder API.
  • When the Apply coupons window is closed, the changeOrder API is called to remove invalid promotions from the order details.
  • The data is not saved permanently against the order until the save button is clicked. Clicking save invokes the existing changeOrder API, which passes the ApplyPendingChanges="Y" attribute.
  • The Edit order page is refreshed with updated data, such as order total and discounts, by calling the existing getCompleteOrderDetails API.
  • The following order modification rules must be enabled by using Applications Manager:
    • CHANGE_PROMOTION
    • REMOVE_PROMOTION
  • The following APIs are called to modify the order by applying or removing coupons:
    • getCompleteOrderDetails. To get the list of applied coupons and to refresh the order data after adding or removing the coupon.
    • translateBarCode with BarCodeType="StoreCoupon". To translate coupon bar code.
    • changeOrder. To add a new coupon with Promotion action as CREATE and to remove a coupon with Promotion action as REMOVE.

Modifying the gift options

As a store associate, you can mark a new or existing order line as a gift.
  • You cannot modify the gift options for existing CARRY lines that are already carried by the customer.
  • You can make changes to the gift options for existing Ship and Pick order lines based on the configured modification permissions.
  • You can mark any newly added order line as a gift. The option to mark an order line as a gift is enabled only if MaxLineStatus < 3350 (Included in shipment) and is not equal to 1100.7777 (CARRIED).
  • The Gift options button at the order level is available only when at least one of the order lines is valid for applying the gift options and has modification permissions. In all other cases, you can use Gift options at the order line level.
  • The modifyFulfillmentOptions API is called to update the gift information in the order.
  • The pending changes are committed only on clicking Save by calling the changeOrder API.
  • The following order modification rules must be enabled by using Applications Manager:
    • CHANGE_GIFT_FLAG
    • CHANGE_GIFT_WRAP
    • MARKFOR
    • CHANGE_INSTRUCTION
  • The following APIs are called to modify the gift options:
    • getCompleteOrderLineList. To get details of the gift options that are applied at the order line level.
    • getCompleteOrderDetails. To get the order details.
    • modifyFulfillmentOptions. To update the gift information in the order.
    • changeOrder. To commit the changes to the database.

Modifying the address

As a store associate, you can change the customer address in an existing order from the Edit order page.
  • The ISF000062 resource permission is required to change the order address.
  • You can modify the order address only f maxOrderStatus < 1500 (Scheduled)
  • Clicking the customer name link in the Edit order page opens the Identify customer window. You can edit the current address that is displayed by clicking Edit shipping address. On changing the order address, any order lines that are associated with the order address are also updated with the new address.
  • The updated address is saved against the order only when the Save button is clicked in the Edit order page. Clicking Save invokes the existing changeOrder API on the page, which passes the ApplyPendingChanges="Y" attribute.
  • The following APIs are called to modify the address:
    • verifyAddress. To verify the address.
    • modifyFulfillmentOptions. To update the order with the new address.

Adding notes at the order line and order level

  • The ISF000057 (AddCommentsToOrder) resource permission is required to add new notes. If you do not have this resource permission, you can only view the existing notes.
  • Clicking the Notes link in the order line level opens the Product notes window displaying all the added notes. You can click Add new note to add order line level notes.
  • You can also click the Notes option in the Actions menu to open the Notes window, which displays all the notes added at the order level. You can click Add new note to add order level notes.
  • Notes do not require invoking ApplyPendingChangesbecause the notes are directly saved to the order.
  • The ADD_NOTE order modification rule must be enabled by using Applications Manager.

Capturing payment for change in order total

  • On adding a new order line, a message is displayed with the new order total and the pending payment details.
  • On saving the changes in the Edit order page, a confirmation message is displayed with a link to proceed to the Capture payment page.
  • In the Capture payment page, you can also view the previously captured payments if any. You can capture the due amount to complete the payment.
  • After the entire amount is paid, the Order summary page opens.

Processing refund for the canceled order lines

After modifying an order, if the new order total is less then the paid amount, you can process the refund of the excess amount.
  • On canceling an order line, a message is displayed with the new order total and refund details:
    • If the amount is charged, the exact refund amount is shown.
    • If the refund amount is authorized, the authorized amount is reversed shortly. The message does not display the exact authorized refund amount.
    • If amount is charged and authorized, the exact refund amount is shown and the authorized amount is reversed shortly.
  • If any payment or refund of the charged, but not authorized, amount is pending for a saved order, a warning message is displayed.
  • When you save the changes, refund is also processed in the background by using the processOrderPayments API. A confirmation message is displayed in the Edit order page along with the refund summary.

    If the processOrderPayments API fails, an error message along with a retry option is displayed. Clicking retry invokes the processOrderPayments API. If the API repeatedly fails, you have the option to navigate to the Order summary page. Then, you can retry by editing the order again or the refund will be automatically processed after some time.