Refund return rules | Magento Order Management Documentation (Archived)

In order to process returns and refunds in your Order Management Service (OMS), you must enable and configure some rules and permissions to define how refunds work.

Rules

These rules configure the expected behavior for the refund return services in your OMS.

Enable rules

To enable the refund return rules functionality, toggle the refund return rules options in the System Integrator (SI) Portal—Sales channel > Post-sales > Refund return rules.

See the Postsales category page for more information.

Toggling these options to enable the functionalities ensures that refund return rules can be managed in your OMS.

Sales channel > Post-sales > Refund return rules

Functionalities

These definitions are previously configured by your SI within your SI Portal, which is not accessible externally yet. Contact Magento support to change this configuration.

Permissions

After refunds are enabled in your SI Portal you must also enable the correct permissions per user in the OMS Admin. To enable this functionality to appear in your OMS Admin:

Ensure you are assigned the correct permissions to access this configuration and functionality. In your OMS Admin navigate to System > Roles.
Click the applicable roles.
Ensure the Refund management options in the Customer Service section are selected.

Return order service

With the ReturnServiceOrder option, you can include (or not) order services in the return when a return is completed.

Example of an order_line as a service line

{
    "id": "x",
    "line_number": 4,
    "product_type": "SERVICE",
    "sku": "23456",
    "product_name": "ITEM_Delivery",
    "shipping_address_reference": "n123",
    "payment_reference": "15",
    "amount": {
        "net_amount": 5,
        "gross_amount": 5,
        "tax_amount": 0,
        "tax_rate": 0,
        "taxes": [
            {
                "type": "VAT",
                "amount": 0,
                "rate": 0
            }
        ],

This information appears in the magento.sales.order_management.create message as a product_type: "SERVICE" and indicates that this specific order_line is a service line. This configuration is received by your OMS and it is processed accordingly. However, you cannot see the service line as one item of your shipment in your Customer service view in the OMS.

If this configuration is enabled in your SI portal, the service line is always returned with the first requested return.

The service line is shown in the Returns view in the OMS for that specific order. If the return for the order line is approved, the service line is automatically approved.

Return line service

With the ReturnServiceLine option, you can include service lines in the returns when a return is completed.

Example of an order_line with a parent_line

{
    "id": "xx",
    "line_number": 4,
    "product_type": "SERVICE",
    "sku": "23456",
    "product_name": "ITEM_Delivery",
    "parent_line_number": 2,
    "shipping_address_reference": "29",
    "payment_reference": "15",
    "amount": {
        "net_amount": 5,
        "gross_amount": 5,
        "tax_amount": 0,
        "tax_rate": 0,
        "taxes": [
            {
                "type": "VAT",
                "amount": 0,
                "rate": 0
            }
        ],

This information appears in the magento.sales.order_management.create message as a product_type: "SERVICE" and indicates that this specific order_line is a service line. In this case, the magento.sales.order_management.create message includes a parent_line for this specific order_line. The service line appears as one of the items of the shipment in your Customer service view in the OMS.

If this configuration is enabled in your SI portal, the service line is always returned with the first requested return.

The service line is shown in the Returns view in the OMS for that specific order. If the return of the parent_line is approved, the service line is automatically approved.

Shipping refund Rule

With the ShippingRefundRule option you can decide how to include the shipping line in the return:

onFirst—Shipping item will be included in the return when one or more lines belonging to this shipping item are returned.
onLast—Shipping item will be included in the return when all lines belonging to this shipping item are returned.
never—Shipping item will never be included in the return.

Returns including an order line with a service, such as gift wrap, are authorized and do not show a 500 error. It is required that returnServiceOrder and returnServiceItem are enabled. Then, the expected behavior is that all lines will be refunded if they have an associated cost.

Reshipping order line

There is another rule that occurs for reshipments. When an order line is shipped and a reshipment is processed against that order line, a return is requested for that original order line.

The expected behavior is that the original line should be returned and no refund must be applied to that order line.

When a new reshipment action is selected, a magento.postsales.reshipment.management.create message is sent.

Example of a magento.postsales.reshipment.management.create message:

{
    "reshipment": {
        "sales_channel_id": "ST1",
        "order_id": "12345",
        "new_shipping_method": "flatrate Fixed",
        "new_shipping_address": {
            "first_name": "Veronica",
            "last_name": "Costello",
            "company_name": "",
            "address1": "6146 Honey Bluff Parkway",
            "address2": "",
            "city": "Calder",
            "zip": "49628-797",
            "state": "MI"
        },
        "lines": [
            {
                "line_number": 2,
                "reason": "Warehouse mistake",
                "reason_description": "Wrong item"
            }
        ]
    },
    "user": "you@youremail.com"
}

The order_id field corresponds to the original order line from the order. A new reshipment order is created as a child order of the original order.

A magento.logistics.shipment_request_management.requested message is sent from the new reshipment order.

Example of a magento.logistics.shipment_request_management.requested message:

{
    "shipment_request": {
        "id": "ST1-R00000548-01",
        "order_id": "R00000548",
        "source_id": "SOU1",
        "customer_id": "1",
        "store": "ST1",
        "language": "en_US",
        "vat_country": "US",
        "origin": "RE",
        "origin_date": "2020-02-17T11:29:46+00:00",
        "created_at": "2020-02-17T11:29:54+00:00",
        "status": "NEW",
        "items": [
            {
                "order_line_id": "2",
                "order_line_number": 1,
                "item_type": "PHYSICAL",
                "sku": "24-MB04",
                "name": "my lovely item",
                },
                {
                "order_line_promotions_info": {
                    "original_price": 35.72,
                    "promotions": []
                },
                "status": "NEW",
                "status_reason": "ITEM_PENDING_PICKING",
                "status_date": "2020-02-17T11:29:54+00:00"
            },
            {
                "order_line_id": "3",
                "order_line_number": 2,
                "item_type": "SHIPPING",
                "sku": "STANDARD",
                "name": "SHIPPING",
                "order_line_price": {
                    "net_amount": 0,
                    "gross_amount": 0,
                    "tax_amount": 0,
                    "tax_rate": 0,
                    "taxes": [
                        {
                            "type": "VAT",
                            "amount": 0,
                            "rate": 0
                        }
                    ]
                },
                "order_line_promotions_info": {
                    "original_price": 35.72,
                    "promotions": []
                },
                "status": "NEW",
                "status_reason": "ITEM_PENDING_PICKING",
                "status_date": "2020-02-17T11:29:54+00:00"
            }
        ],
        "addresses": [
            {
                "reference": "1",
                "address_type": "customer",
                "first_name": "Veronica",
                "last_name": "Costello",
                "address1": "6146 Honey Bluff Parkway",
                "city": "Calder",
                "state": "MI",
                "zip": "49628-797",
                "country_code": "US",
                "phone": "(555) 229-3326",
                "email": "you@youremail.com",
                "custom_attributes": []
            },
            {
                "reference": "5e4a792a431ee7.34701732",
                "address_type": "customer",
                "first_name": "Veronica",
                "last_name": "Costello",
                "address1": "6146 Honey Bluff Parkway",
                "city": "Calder",
                "state": "MI",
                "zip": "49628-797",
                "country_code": "US",
                "phone": "(555) 229-3326",
                "email": "you@youremail.com",
                "custom_attributes": []
            }
        ],
        "shipping_address": {
            "reference": "5e4a792a431ee7.34701732",
            "address_type": "customer",
            "first_name": "Veronica",
            "last_name": "Costello",
            "address1": "6146 Honey Bluff Parkway",
            "city": "Calder",
            "state": "MI",
            "zip": "49628-797",
            "country_code": "US",
            "phone": "(555) 229-3326",
            "email": "you@youremail.com",
            "custom_attributes": []
        },
        "billing_address": {
            "reference": "1",
            "address_type": "customer",
            "first_name": "Veronica",
            "last_name": "Costello",
            "address1": "6146 Honey Bluff Parkway",
            "city": "Calder",
            "state": "MI",
            "zip": "49628-797",
            "country_code": "US",
            "phone": "(555) 229-3326",
            "email": "you@youremail.com",
            "custom_attributes": []
        },
        "status_date": "2020-02-17T11:29:54+00:00"
    }
}

Finally, a magento.sales.order_management.updated message is sent from this new reshipment order to notify of any changes.