Pre-authorised returns

Pre-authorised returns are returns that the customer initiates, due to one of a multitude of possible reasons.

Customer workflow

Pre-authorised returns occur in a prescribed customer flow:

  1. The customer can initiate the return by calling Customer Service or requesting it via their MyAccount login on the frontend.

    This manual request for a pre-authorised return can be caused by several 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 in their side, as their system only allows them to scan the goods when the Return Merchandise Authorization (RMA) is already imported in their systems.
  2. 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 at some point.
  3. The customer completes the return label and sends the package to the carrier.

    To learn how to link a return label to the OMS, to request an RMA, see the Configure RMAs section.

  4. 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.
  5. The OMS will calculate the refund associated to the return, based on the retailer refund rules, and generates the required notifications to perform the payment refund.
  6. If the return package does not arrive to the warehouse due to a carrier mistake (the most common use case is that 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.
    1. 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.
    2. 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.
  7. The OMS sends a notification to payments and the refund will be triggered to the customer.

Diagram

Integration

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

     {
         "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"
                 }
             ]
         }
     }
    
  2. If you want to change the source that handles the request, specify the source in the following field:

     {
         "return": {
             ..
             "source_id": "NEW_SOURCE",
             ..
         }
     }
    
  3. The OMS will send an updated message, #magento.postsales.return_management, to communicate that the return has been successfully requested for all systems related to synchronization:

     {
     "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"
         }
         ]
     }
     }
    

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

  4. The OMS will also send a specific request message, #magento.postsales.return_management, to the warehouse to communicate needed information in advance of the return that will arrive.
  5. Once the warehouse has received the returned goods they will send the OMS a received message, #magento.postsales.return_management, that records the return in the OMS:

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

    ll 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 only needs to 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.

  6. The OMS will approve it and send an updated message, #magento.postsales.return_management, to all connected systems:

     {
         "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"
                 }
             ]
         }
     }
    

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

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

     {
         "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 return merchandise authorization (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 a return merchandise authorization (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 SFS or 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 SI must intercept the updated message that includes all relevant return info and contact the carrier integration API to request a RMA label

     {
         "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"
               }
           ]
       }
     }
    
  3. The SI uses the magento.postsales.return_management update specification to communicate the return link, tracking number, return carrier, and more.

     {
       "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.