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.

Exchanges

The exchange functionality in Order Management System (OMS) allows the Customer Service (CS) agent to exchange an item from an order.

See the Exchanges Customer Service user guide topic for more information.

Use case

Exchanges can be used when customer satisfaction is low. If a customer is not happy with some of the order items (order lines) they received they can exchange their item(s) for another variant, such as if an item is too big or small and they need a different size.

This scenario is usually generated by a call to customer service. After the request to exchange an order item for a different variant, a new order will be generated and linked to the previous order to provide correct visibility and manage refunds for any returns that are also generated.

Example of an Exchange order

{
    "exchange": {
        "order_id": "100000000000001",
        "store_id": "Luma Retail Stores - Southeast",
        "lines": [
            {
                "id": "243",
                "line_number": "1"
            }
        ]
    }
}

An order line which was previously exchanged cannot be exchanged again.

Flow

The following exchange flows are configurable per store:

  • Exchange items are directly sent to the end customer without waiting for the exchanged lines to be received by the warehouse.
  • Exchange items are maintained in an ON HOLD status until the exchanged lines have been received in good condition by the warehouse.

Solution considerations

Consider the following when implementing an exchange:

  • The exchanged items are associated with a new order.
  • This new order is linked to the previous one so that you can find the relationship in the order updated message in the original_order_id field.

    Example of the magento.sales.order_management.updated message with exchange information

      {
          "order": {
              "id": "E00080001",
              "original_order_id": "100000000000001"}
               }
    
  • This new order has the ZEROPAY payment method and the payment amount is 0 for this type of order.
  • When a line is exchanged, this line is automatically flagged to be returned in the following days.
  • This type of order is accessible in an origin field with the constant EX:

    Example of order accessible in origin

      {
          "order": {
              "id": "E00080001",
              "original_order_id": "100000000000001",
              "origin": "EX"},
              }
    
  • An order line which was previously exchanged cannot be exchanged again.

Configurable exchanges features

The current exchanges features are available for all clients but should be activated/deactivated via a feature flag.

Change shipping method

The change shipping method feature allows you to select a different shipping method for the reshipped order. This field is optional, and if it is not specified the order will be shipped with the previous shipping method.

Changing the shipping address will not impact the amount captured from the customer, as it is a 0 price order. The shipping method must be part of the catalog or available shipping methods.

Example of an exchange with a changed shipping method

{
    "exchange": {
        "order_id": "100000000000001",
        "store_id": "Luma Retail Stores - Southeast",
        "new_shipping_method": "EXPRESS",
        "lines": [
            {
                "id": "243",
                "line_number": "1"
            }
        ]
    }
}

Change shipping address

The change shipping address feature allows you to select a different shipping address for a reshipped order. This field is optional, and if it is not specified the order will be shipped with the previous shipping address.

The OMS does not verify addresses, so it is the responsibility of the system that trigger this messages to complete this process if it is required.

Example of an exchange with a changed shipping address

{
    "exchange": {
        "order_id": "100000000000001",
        "store_id": "Luma Retail Stores - Southeast",
        "lines": [
            {
                "id": "243",
                "line_number": "1"
            }
        ],
        "new_shipping_address": {
            "address1": "7700 W Parmer Ln",
            "address2": "",
            "city": "Austin",
            "company_name": "Magento",
            "first_name": "John",
            "last_name": "Doe",
            "state": "TX",
            "zip": "78729"
        }
    }
}

Order ID

The order_id field allows you to specify the external order ID, if the order was generated in a different system, to help maintain a well synchronized system. The combination of store ID and order ID must be unique. If the order_id field is not specified, the OMS will generate the order ID automatically with a ā€˜Eā€™ prefix.

Example of an exchange with a specified external order ID

{
    "exchange": {
        "order_id": "100000000000001",
        "store_id": "Luma Retail Stores - Southeast",
        "new_order_id": "2000000000000101",
        "lines": [
            {
                "id": "243",
                "line_number": "1"
            }
        ]
    }
}

Return considerations

Consider the following when configuring and performing returns for exchanged orders:

  • The exchanged line is flagged in the OMS Admin to to indicate a return has not yet received for this line.
  • A return of an exchange order should be only available when the line of the parent order was already returned.
  • A return of an exchange item will not generate any refund when the parent line is returned.
  • The money of an exchange line will be only refunded in the case that a return is received first for the parent line and secondly for the exchanged item.

To learn more about the way that these entities are displayed out-of-the box in the OMS see the Customer Service user guide topic for moe information.

Appeasements for exchange refunds

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.

See the Refunds topic for detailed process information.

Cancellation considerations

Consider the following when configuring and performing cancellations for exchanged orders:

  • An exchange can only be cancelled with an ON_HOLD status with a pending_return_parent_order status reason.
  • Once an exchange is cancelled, its pending_return label is removed from the parent order.
  • An exchange can only be cancelled if the return of the parent order has not been requested.

Exchange out-of-stock

When an out-of-stock item is requested in an exchange order, you can cancel the order and return the parent order. To cancel an exchange, the backorder functionality in the OMS must be disabled.

You can manage the backorder configuration in your SI Portal, which is not yet accessible externally. Contact Magento Support for assistance.

See the Backorders topic for more information.

Once the exchange is canceled, a new appeasement must be created in the parent order so the refund is released to the customer.

See the Appeasements topic for more information.