Manage the Workflow for Modified Orders

The application using the Order Update API is responsible for managing the workflow for a modified order and making all necessary API calls. Depending on the changes made to the order, the workflow for a modified order can be as complex as the shopping cart workflow for a brand new order. For example:

  • If address information was changed, call the Address Validation API. A shipping address change might require recalculation of shipping costs, and taxes.
  • If items are added or removed or quantities changed, call the Inventory API.
  • If items, quantities, shipping address, or shipping method were changed, recalculate shipping costs, taxes, and duties.
  • If any changes affect order pricing, make the appropriate calls to the Payment API.
  • Submit the modified order for fraud/risk clearance, just as if it were a new order. If the modification is done by a customer service call agent, include the agent ID with the order modification data submitted for risk analysis. For more information, see Fraud Processing for Modified Orders

The following diagram shows an example workflow for a modified order. Not all of the steps and API calls shown in the diagram are needed for every modified order; the details depend on the types of modifications made. For each numbered item in the diagram, see discussion below.

The following numbered actions correspond to the numbers in the workflow diagram above.

  1. Order Details. After a consumer requests changes in a recently submitted order, a customer service agent must first locate the consumer's order and retrieve the order information with an Order  Detail Request. The Order Detail response includes the detailed order data and indicates which portions of the order data are eligible to be modified. For more information, see the Modified Order Details and the Order API page.
  2. Order Modification Hold. If the order is eligible to be modified, the order must be placed on hold before modifications begin. The Order Hold request confirms that the order can be placed on hold successfully, and the hold prevents the order from proceeding to fulfillment while the order is being modified. For more information, see Order Hold.
  3. Inventory Get. The customer service agent adds and removes items and changes quantities as needed. For new items or increased quantity, the ordering application must obtain a new inventory reservation. For items that remain unchanged from the original order, the original order's inventory reservation can be used. For information on Inventory API calls, see Inventory API. For other considerations during this part of the process, see Manage Shopping Cart Changes.
  4. Address Validation. If the shipping address changes, the ordering application must validate the address with an Address Validation request. For more information, see Address Validation API. The ordering application must also recalculate shipping prices and fees that results from any shipping changes.
  5. Tax. The ordering application must recalculate tax and duties if the order has any changes involving the selection and price of products or the shipping address or fulfillment location. If tax is not recalculated, there will be a discrepancy between the amount collected from the consumer and the amount required to be remitted to the local jurisdictions, which the merchant will be responsible to reconcile and fund.

    Note: To simplify application logic and prevent any possible discrepancy, an application can simply recalculate tax for all modified orders.

    For more information, see Tax API.

  6. Payment. The exact payment processing for a modified order depends both on the total amount (as compared to the original order's total) and the payment tenders used. In many cases, the payment from the original order is voided and a new payment is authorized for the modified order. For more information see Manage Payments for Modified Orders, and the Payment API page.
  7. Inventory Allocate. When the modified order is submitted, the ordering application must make an Inventory Allocate request to allocate any items added to the order during the modification process. For more information, see the Inventory API page.
  8. Order Update. The ordering application submits the modified order through a request to the Order Update API. For more information, see the Order Update page.
  9. Release Hold. The ordering application must release the order modification hold on the original order. This can be accomplished as part of the Order Update request in step 8, or through a separate Order Hold request. The modified order then takes the place of the original order. It proceeds through the remaining steps of the normal order process, including buyer's remorse hold, fraud hold, and fulfillment. For more information, see Release a Hold on an Order.
  10. Fraud Data Submission. When an order is modified, the modified order must be submitted for fraud risk assessment. For more information, see Fraud Processing for Modified Orders.

When the modified order is submitted, the order system records a Change Order Event. You can configure an email template so that the Change Order Event automatically triggers an email to the consumer with information about the changed order.