How to Handle an Order Edit in Storefront

In this document, you’ll learn how to allow a customer to confirm or decline an Order Edit.

---

Overview

A merchant can request to edit an order to make changes to its items. The change can include removing an item, adding a new item, and changing the quantity of an item in the original order.

When the Order Edit is in the “request” state, it requires either a confirmation from the customer, or it can be force-confirmed by the merchant.

This guide focuses on how to use the Storefront APIs to implement the flow that allows a customer to either confirm or decline an Order Edit.

You can check out how to implement order editing using the Admin APIs in this documentation.

Scenarios

You want to implement the following functionalities in your storefront:

• List and show customers order-edit requests.
• Confirm order edits and authorize any additional payment if necessary.
• Decline order edits.

You can perform other functionalities related to order editing. To learn more, check out the API reference.

---

Prerequisites

Medusa Components

It's assumed that you already have a Medusa backend installed and set up. If not, you can follow our quickstart guide to get started.

It is also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install the Next.js Starter Template.

JS Client

This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client and JavaScript’s Fetch API.

If you follow the JS Client code blocks, it’s assumed you already have Medusa’s JS Client installed and have created an instance of the client.

Medusa React

This guide also includes code snippets to send requests to your Medusa backend using Medusa React, among other methods.

If you follow the Medusa React code blocks, it's assumed you already have Medusa React installed and have used MedusaProvider higher in your component tree.

Previous Steps

You must have an existing order edit in the “request” state.

---

Retrieve an Order Edit

You can retrieve a single order edit by its ID by sending a request to the Get Order Edit endpoint:

• Medusa JS Client
• Medusa React
• Fetch API

medusa.orderEdits.retrieve(orderEditId)
.then(({ order_edit }) => {
  console.log(order_edit.changes)
  // show changed items to the customer
})

Report Incorrect CodeCopy to Clipboard

import { useOrderEdit } from "medusa-react"

const OrderEdit = () => {
  const { order_edit, isLoading } = useOrderEdit(orderEditId)

  // ...
}

export default OrderEdit

Report Incorrect CodeCopy to Clipboard

fetch(`<BACKEND_URL>/store/order-edits/${orderEditId}`)
.then((response) => response.json())
.then(({ order_edit }) => {
  console.log(order_edit.changes)
  // show changed items to the customer
})

Report Incorrect CodeCopy to Clipboard

The request requires the order edit’s ID as a path parameter.

It returns the Order Edit as an object. Some of its important fields are:

• order_idCopy to Clipboard: The ID of the order that this Order Edit belongs to.
• difference_dueCopy to Clipboard: The amount to either be refunded or paid. If the amount is greater than 0, then the customer is required to pay an additional amount. If the amount is less than 0, then the merchant has to refund the difference to the customer.
• payment_collection_idCopy to Clipboard: The ID of the payment collection. This will be used to authorize additional payment if necessary.

You can learn more about what fields to expect in the API reference.

Show Changed Items

All data about changes to the original order’s items can be found in order_edit.changesCopy to Clipboard. changesCopy to Clipboard is an array of item changes. Each item change includes the following fields:

{
  type: string,
  line_item: LineItem | null,
  original_line_item: LineItem | null
}

Report Incorrect CodeCopy to Clipboard

typeCopy to Clipboard can be either:

• item_addCopy to Clipboard: In this case, a new item is being added. line_itemCopy to Clipboard will be an item object and original_line_itemCopy to Clipboard will be nullCopy to Clipboard.
• item_updateCopy to Clipboard: In this case, an item’s quantity in the original order is updated. line_itemCopy to Clipboard will be the updated item, and original_line_itemCopy to Clipboard will be the item in the original order. You can either just use line_itemCopy to Clipboard to show the new quantity, or show the customer a comparison between the old and new quantity using original_line_itemCopy to Clipboard as well.
• item_removeCopy to Clipboard: In this case, an item in the original order is removed. The original_line_itemCopy to Clipboard will be the item in the original order, and line_itemCopy to Clipboard will be nullCopy to Clipboard.

Here’s an example of how you can use this data to show the customer the requested edits to the order:

<ul>
  {orderEdit.changes.map((itemChange) => (
    <li key={itemChange.id}>
      <strong>
        {
          itemChange.line_item ? 
          itemChange.line_item.title : 
          itemChange.original_line_item.title
        }
      </strong>
      {itemChange.type === "added" && <span>New Item</span>}
      {itemChange.type === "removed" && (
        <span>Removed Item</span>
      )}
      {itemChange.type === "edited" && 
        <span>
          Edited Item
          Old Quantity: {itemChange.original_line_item.quantity}
          New Quantity: {itemChange.line_item.quantity}
        </span>}
    </li>
  ))}
</ul>

Report Incorrect CodeCopy to Clipboard

---

Handle Payment

After viewing the changes in the order edit, the customer can choose to confirm or decline the order edit.

In case the customer wants to confirm the order edit, you must check whether a refund or an additional payment is required. You can check that by checking the value of difference_dueCopy to Clipboard.

Refund Amount

If difference_dueCopy to Clipboard is less than 0, then the amount will be refunded to the customer by the merchant from the Medusa admin. No additional actions are required here before completing the order edit.

Make Additional Payments

This section explains how to authorize the payment using one payment processor and payment session. However, payment collections allow customers to pay in installments or with more than one provider. You can learn more about how to do that using the batch endpoints of the Payment APIs

If difference_dueCopy to Clipboard is greater than 0, then additional payment from the customer is required. In this case, you must implement these steps to allow the customer to authorize the payment:

1. Show the customer the available payment processors. These can be retrieved from the details of the region of the order.
2. When the customer selects the payment processor, initialize the payment session of that provider in the payment collection. You can do that by sending a request to the Manage Payment Sessions endpoint, passing it the payment collection’s ID as a path parameter, and the payment processor's ID as a request body parameter:

• Medusa JS Client
• Medusa React
• Fetch API

medusa.paymentCollections.managePaymentSession(paymentCollectionId, {
  provider_id,
})
.then(({ payment_collection }) => {
  console.log(payment_collection.payment_sessions)
})

Report Incorrect CodeCopy to Clipboard

import { useManagePaymentSession } from "medusa-react"

const OrderEditPayment = () => {
  const managePaymentSession = useManagePaymentSession(
    paymentCollectionId
  )
  // ...

  const handleAdditionalPayment = (provider_id: string) => {
    managePaymentSession.mutate({
      provider_id,
    })
  }

  // ...
}

export default OrderEditPayment

Report Incorrect CodeCopy to Clipboard

fetch(
  `<BACKEND_URL>/store/payment-collections/${paymentCollectionId}/sessions`,
  {
    method: "POST",
    credentials: "include",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      provider_id,
    }),
  }
)
.then((response) => response.json())
.then(({ payment_collection }) => {
  console.log(payment_collection.payment_sessions)
})

Report Incorrect CodeCopy to Clipboard

1. Show the customer the payment details form based on the payment session’s provider. For example, if the provider ID of a payment session is stripeCopy to Clipboard, you must show Stripe’s card component to enter the customer’s card details.
2. Authorize the payment using the payment processor. The Authorize Payment Session endpoint accepts the payment collection’s ID and the ID of the payment session as path parameters:

• Medusa JS Client
• Medusa React
• Fetch API

medusa
  .paymentCollection
  .authorizePaymentSession(
    paymentCollectionId, 
    paymentSessionId
  )
.then(({ payment_session }) => {
  console.log(payment_session.id)
})

Report Incorrect CodeCopy to Clipboard

import { useAuthorizePaymentSession } from "medusa-react"

const OrderEditPayment = () => {
  const authorizePaymentSession = useAuthorizePaymentSession(
    paymentCollectionId
  )
  // ...

  const handleAuthorizePayment = (paymentSessionId: string) => {
    authorizePaymentSession.mutate(paymentSessionId)
  }

  // ...
}

export default OrderEditPayment

Report Incorrect CodeCopy to Clipboard

fetch(
  `<BACKEND_URL>/store/payment-collection/${paymentCollectionId}` + 
  `/sessions/${paymentSessionId}/authorize`, 
  {
    method: "POST",
    credentials: "include",
  }
)
.then((response) => response.json())
.then(({ payment_session }) => {
  console.log(payment_session.id)
})

Report Incorrect CodeCopy to Clipboard

After performing the above steps, you can complete the Order Edit.

---

Complete the Order Edit

To confirm and complete the order edit, send a request to the Complete Order Edit endpoint:

• Medusa JS Client
• Medusa React
• Fetch API

medusa.orderEdits.complete(orderEditId)
.then(({ order_edit }) => {
  console.log(order_edit.confirmed_at)
})

Report Incorrect CodeCopy to Clipboard

import { useCompleteOrderEdit } from "medusa-react"

const OrderEdit = () => {
  const completeOrderEdit = useCompleteOrderEdit(orderEditId)
  // ...

  const handleCompleteOrderEdit = () => {
    completeOrderEdit.mutate()
  }

  // ...
}

export default OrderEdit

Report Incorrect CodeCopy to Clipboard

fetch(`<BACKEND_URL>/store/order-edits/${orderEditId}/complete`, {
  method: "POST",
  credentials: "include",
})
.then((response) => response.json())
.then(({ order_edit }) => {
  console.log(order_edit.confirmed_at)
})

Report Incorrect CodeCopy to Clipboard

This request accepts the order edit’s ID as a path parameter.

It returns the full Order Edit object. You can find properties related to the order confirmation, such as order_edit.confirmed_atCopy to Clipboard.

After completing the order edit, the changes proposed in the Order Edit are reflected in the original order.

If the payment isn’t authorized first, the order edit completion will fail.

---

Decline an Order Edit

If the customer wants to decline the Order Edit, you can do that by sending a request to the Decline Order Edit endpoint:

• Medusa JS Client
• Medusa React
• Fetch API

medusa.orderEdits.decline(orderEditId, {
  decline_reason: "I am not satisfied",
})
.then(({ order_edit }) => {
  console.log(order_edit.declined_at)
})

Report Incorrect CodeCopy to Clipboard

import { useDeclineOrderEdit } from "medusa-react"

const OrderEdit = () => {
  const declineOrderEdit = useDeclineOrderEdit(orderEditId)
  // ...

  const handleDeclineOrderEdit = () => {
    declineOrderEdit.mutate({
      declined_reason: "I am not satisfied",
    })
  }

  // ...
}

export default OrderEdit

Report Incorrect CodeCopy to Clipboard

fetch(
  `<BACKEND_URL>/store/order-edits/${orderEditId}/decline`, 
  {
    method: "POST",
    credentials: "include",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      decline_reason: "I am not satisfied",
    }),
  }
)
.then((response) => response.json())
.then(({ order_edit }) => {
  console.log(order_edit.declined_at)
})

Report Incorrect CodeCopy to Clipboard

The request requires passing the order edit’s ID as a path parameter.

In the request body parameters, you can optionally pass the decline_reasonCopy to Clipboard parameter. It’s a string that indicates to the merchant the reason the customer declined the order edit.

If the Order Edit is declined, the changes requested in the Order Edit aren't reflected on the original order and no refund or additional payments are required.

---

See Also

• Edit an order using Admin APIs