Order Management System (OMS) reached end of support in October 2024.
The documentation available here is intended for historical reference only and is not maintained.
For other Commerce-related documentation, see Adobe Commerce Documentation.

Refunds

The Magento Order Management System (OMS) allows you to manage refunds for any order in the Admin UI or via the API.

The way you handle refunds depends on the type of payment integration that was implemented by your System Integrator (SI)—either CUSTOM or OFFLINE.

The codes and reason_codes in the magento.postsales.refund_management.updated specification can be different, depending on the applied payment integration—CUSTOM or OFFLINE. See the Payments page for more information.

See the Auto release refund topic for more information about how to manually approve a refund for an order or for order lines.

Refunding an exchange

When a customer wants to return items that were previously sent as an exchange of their original order, and the Auto approve return configuration is disabled, the refund of the original order is not automatically released.

The CSA must approve the return in the exchange order first to release the refund in the parent/original order.

The process of returning an exchange follows this general process:

  1. An order containing multiple order lines is shipped to a customer.
  2. The customer wants to exchange the first line of the order. A new exchange order is created with an On hold status.
  3. After creating the exchange, the CSA must create a return of the same line in the original order so the customer returns the item they received in the original order (and that they decided to exchange).
  4. The CSA must approve the return in the original order. The return has no associated refund for the order because it is associated with the exchange. Once the return is approved, the exchange order moves to a Logistics in Progress status.
  5. After receiving the shipped exchange order, the customer decides they want to return the exchange item. The CSA must create a return of this item in the exchange order and then approve the return. When the exchange order is approved, a “This return does not have any associated refund in this order. When this return is approved, a refund will be generated in the parent order.” message appears.
  6. In the Customer service view > Appeasements section, now the parent order displays a “This refund was generated based on a return in a child order E00000000.”
  7. In the Order details view > Payments section, you see a line item denoting the successful refund.

    The above process is an example to illustrate the expected flow. Each situation may differ, depending on the specific order, lines within the order, etc.

CUSTOM payment integrations

For CUSTOM payment integrations, a magento.postsales.refund_management.updated message is sent just before the refund is requested from the payment gateway:

{
"code":"PENDINGRELEASE",
"reason_code":"REQUESTED"
}

Then, a new message is sent when notification is received from the payment gateway.

Success—A magento.payments.payments_management.notify_refunded message is received with:

  {
  "code":"RELEASED",
  "reason_code":"RELEASESUCCESS"
  }
  {
  "code":"PENDINGRELEASE",
  "reason_code":"RELEASEFAILED"
  }

OFFLINE payment integrations

For OFFLINE payment integrations, only one magento.postsales.refund_management.updated message is sent. It always contains the same code and reason_code:

{
"code":"RELEASED",
"reason_code":"REQUESTED"
}

After the above message is sent, the OMS completes the refund operation, the item or order is ready to be refunded, and Magento Commerce (MC) issues the refund.