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.

Pre-authorised returns

Pre-authorised returns are returns that the customer initiates, due to many potential reasons.

Customer workflow

Pre-authorised returns typically occur in a prescribed customer flow:

  1. The customer initiates the return by calling Customer Service or requesting it via their MyAccount login on the front-end due to reasons such as:
  • The package received does not have a return label so the customer cannot initiate a typical return.
  • The product to be returned has special characteristics and requires prior manual action to approve this transaction.
  • The carrier cannot generate a return, as their system only allows them to scan the goods when the Return Merchandise Authorization (RMA) is already imported in their systems.
  1. The OMS has all the needed information from the customer and sends a notification to the Logistic Service Provider (LSP) to notify them that they will receive a return from the customer.
  2. The customer completes the return label and sends the package to the carrier.
  3. The warehouse verifies that the product(s) returned are in GOOD condition and if so, the warehouse will inform the OMS that the customer made a return of specific lines of a certain order.
  4. The OMS calculates the refund associated with the return, based on the retailer refund rules, and generates the required notifications to perform the payment refund.
  5. If the return package does not arrive to the warehouse due to a carrier mistake (the most commonly because the customer contacts Customer Service when they do not see a refund in their account after a few days), Customer Service will check the status of the return.
    • Customer service will request that the customer send the carrier receipt, or similar. so that they may contact the carrier for verification. If the receipt is correct, Customer Service will perform a manual return or the customer service tool must send a message to the OMS to generate the approval.
    • If the the package has been lost, Magento and the LSP will work together to solve the problem. If the package arrives to the warehouse later, the OMS will ensure that a refund or reshipment is not duplicated.
  6. The OMS sends a notification to payments and the refund will be triggered to the customer.

    OMS does not update stock with return activity.

    The following diagram illustrates the common customer workflow for pre-authorised returns:

    Pre-authorised returns flow

    Diagram

Integration

Once the customer initiates a return, the OMS will receive a #magento.postsales.return_management.authorize message that creates the return on the OMS side:

Example of an authorize message

  {
      "return": {
           "sales_channel_id": "ST1",
           "order_id": "000000024",
           "user": "userB",
           "custom_attributes": [],
           "lines": [
               {
                   "id": "28",
                   "line_number": 1,
                   "custom_attributes": [],
                   "reason": "TOO_BIG",
                   "reason_description": "Too big size"
               }
           ]
       }
   }

To change the source that handles the request, specify the source in the following field:

   {
       "return": {
           "source_id": "NEW_SOURCE",
       }
   }

The OMS will send a #magento.postsales.return_management.updated message, to communicate that the return has been successfully requested for all systems requiring synchronization:

Example of an updated message

  {
  "return": {
      "sales_channel_id": "string",
      "order_id": "string",
      "source_id": "string",
      "user": "string",
      "rma": "string",
      "return_tracking_number": "string",
      "return_tracking_url": "string",
      "return_tracking_label_url": "string",
      "return_tracking_carrier": "string",
      "custom_attributes": [
      {
          "name": "string",
          "value": "string"
      }
      ],
      "status": {
      "code": "string",
      "name": "string",
      "reason_code": "string",
      "reason_name": "string",
      "date": "datetime"
      },
      "lines": [
      {
          "id": "string",
          "line_number": "integer",
          "sku": "string",
          "status": "string",
          "custom_attributes": [
          {
              "name": "string",
              "value": "string"
          }
          ],
          "reason": "string",
          "reason_description": "string",
          "condition": "string",
          "condition_description": "string"
      }
      ]
  }
  }

The above message is the the out-of-the-box message that the Connector uses to synchronize both systems and create return entities in MDC.

Example of a received message

  {
      "return": {
          "sales_channel_id": "ST1",
          "order_id": "000000024",
          "source_id": "SOU1",
          "user": "userB",
          "rma": "RMA-CS-000000024-1",
          "lines": []
      }
  }

All the lines mentioned in this message are considered in GOOD condition by the OMS. Currently, there is no visibility to the condition of the returned items.

If an order that contains three items is returned, but just two arrive in GOOD condition, the message must only contain those two items. The OMS will automatically cancel the third item and the refund will be recalculated.

For partially approved returns, you must specify the approved list of lines in the lines field.

The OMS approves the return and sends a #magento.postsales.return_management.updated message to all connected systems:

Example of an updated message

     {
        "return": {
            "order_id": "000000024",
            "source_id": "SOU1",
            "user": "userB",
            "rma": "RMA-CS-000000024-1",
            "custom_attributes": [],
            "status": {
                "code": "APPROVED",
                "name": "APPROVED",
                "reason_code": "CSRREQUEST",
                "date": "2017-10-04T11:10:20+00:00"
            },
            "lines": [
                {
                    "id": "28",
                    "line_number": 1,
                    "sku": "WS08-XS-Blue",
                    "status": "APPROVED",
                    "custom_attributes": [],
                    "reason": "TOO_BIG",
                    "reason_description": "Too big size"
                }
            ]
        }
    }

The above message is the out-of-the-box message that the Connector uses to synchronize both systems and create return entities in MDC.

Once a return is generated the refund is calculated and the #magento.postsales.return_management.updated message is sent:

Example of an updated message

    {
        "refund": {
            "order_id": "000000024",
            "store_id": "200001",
            "credit_note_number": "CUS19",
            "credit_note_date": "2017-10-04T11:11:12+00:00",
            "status": {
                "code": "RELEASED",
                "name": "RELEASED",
                "reason_code": "RELEASESUCCESS",
                "reason_name": "RELEASESUCCESS",
                "date": "2017-10-04T11:11:12+00:00"
            },
            "refund_type": "Return",
            "user": "userB",
            "refund_reason": "RELEASESUCCESS",
            "lines": [
                {
                    "order_line": "1",
                    "order_item_id": "28",
                    "payments": [
                        {
                            "details": {
                                "cost_gross": "34.64",
                                "cost_net": "32",
                                "cost_vat": "2.64",
                                "vat_rate": "8.25",
                                "vat_detail": [
                                    {
                                        "type": "VAT",
                                        "amount": "2.64",
                                        "rate": "8.25"
                                    }
                                ]
                            },
                            "status": {
                                "code": "REFUNDED",
                                "name": "REFUNDED"
                            }
                        }
                    ]
                },
                {
                    "order_line": "2",
                    "order_item_id": "SHIPPING",
                    "payments": [
                        {
                            "details": {
                                "cost_gross": "5",
                                "cost_net": "5",
                                "cost_vat": "0",
                                "vat_rate": "0",
                                "vat_detail": [
                                    {
                                        "type": "VAT",
                                        "amount": "0",
                                        "rate": "0"
                                    }
                                ]
                            },
                            "status": {
                                "code": "REFUNDED",
                                "name": "REFUNDED"
                            }
                        }
                    ]
                }
            ],
            "custom_attributes": []
        }
    }

Configure RMAs

When a shipment is made, a return label and return document are included in the package. The customer can then directly ship their returned items using the label and return document.

An approved RMA may be created if:

  • The initial shipment, including all items in the order, has been shipped. In this instance, the warehouse/store can expect that all the items that were shipped will potentially be returned.
  • When the return carrier receives the return label, signifying that the customer shipped the return and the warehouse/store can expect that all the items that were shipped will potentially be returned.

To facilitate an RMA you must communicate with the warehouse and return carrier to ensure that the OMS has the information necessary for return labels.

If you are shipping a Ship from Store (SFS) or Ship to Store (STS) order, or a return, you need a label—carrier integration is applicable to all ordering situations in the OMS. Carrier integration can be configured in the System Integrator (SI) Portal for instances other than returns. For returns, you must use the API to configure RMAs.

To configure an RMA for a created return:

  1. The OMS will notify the warehouse and the OMS front-end that the return has been created.
  2. The System Integrator (SI) must intercept the updated message that includes all relevant return info and contact the carrier integration API to request a RMA label:

Example of an updated message

    {
        "return": {
            "sales_channel_id": "string",
            "order_id": "string",
            "source_id": "string",
            "user": "string",
            "rma": "string",
            "return_tracking_number": "string",
            "return_tracking_url": "string",
            "return_tracking_label_url": "string",
            "return_tracking_carrier": "string",
            "custom_attributes": [
              {
                  "name": "string",
                  "value": "string"
              }
            ],
            "status": {
            "code": "string",
            "name": "string",
            "reason_code": "string",
            "reason_name": "string",
            "date": "datetime"
            },
            "lines": [
            {
                "id": "string",
                "line_number": "integer",
                "sku": "string",
                "status": "string",
                "custom_attributes": [
                {
                    "name": "string",
                    "value": "string"
                }
                ],
                "reason": "string",
                "reason_description": "string",
                "condition": "string",
                "condition_description": "string"
              }
          ]
      }
    }

The SI uses the magento.postsales.return_management.update message to communicate the return link, tracking number, return carrier, and more:

Example of an update message

    {
      "return": {
        "sales_channel_id": "string",
        "order_id": "string",
        "source_id": "string",
        "user": "string",
        "rma": "string",
        "return_tracking_number": "string",
        "return_tracking_url": "string",
        "return_tracking_label_url": "string",
        "return_tracking_carrier": "string",
        "custom_attributes": [
          {
            "name": "string",
            "value": "string"
          }
        ]
      }
    }

For pre-authorised returns, we create the entity of the return; We do not generate a return label.