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.

Shipping address or method

This functionality allows a store associate to change the shipping addresses or shipping methods for a shipping group in the Order Management System (OMS). The shipping group could partially, or fully, impact the order either because one group needs a different shipping address, and another shipping groups has to use a different shipping method.

You can change either the shipping address or method for the different items of your order. If the System Integrator (SI) wants to modify the shipping address or shipping method, when the order is already in the logistics stage, you must cancel the shipment request beforehand.

Modify a shipping address or shipping method via the OMS Admin or via the magento.sales.order_management.create_shipping_line specification.

It is possible to have multiple shipping addresses or methods per order. An order with several shipping addresses or methods is split into several shipment requests (at least one per address or method).

Configuration

To enable this functionality:

  1. Activate the Update Shipping Address option in your SI Portal in Config > Sales Channel > PostSales > Order modification.

  2. In your User & Permissions view, enable or disable this functionality for a certain role, per the rights for that role.

    Roles & Permissions

  3. In your Order view, click Actions > Change Shipping Address to change the shipping address or the shipping method.

    Shipping Address

These definitions are enabled in your SI Portal, which is not yet accessible externally. Contact Magento Support for assistance.

Restrictions

There are some restrictions to this functionality, depending on the order type. A store associate can create a new shipping group and associate order lines to this new group. They can also select an existing address and associate it with an existing shipping group. All the addresses associated with the order must be currently available for selection, including in-store pickup (ISPU) addresses.

Shipping charges

Shipping charges are the shipping costs for an order. When the OMS creates two separate shipment requests it allows for flexibility in assigning these shipping charges to shipments. For example, when the order is sourced from two different locations you can choose which shipping line includes the shipping charges.

For orders with more than one shipment request, you can select where to assign these shipping charges:

  • onFirst—The shipping line is assigned to the first generated shipment request.
  • onLast—The shipping line is assigned to the last generated shipment request.

See the SI Portal Post-sales topic for more information on this feature.

If the shipping line that contains the shipping charges in a shipment request is cancelled, these shipping charges are assigned to the next available shipment request to ensure that the merchant receives these charges.

See the Return refund rules topic for more information on the refund rules associated with post-sales.

Re-sourcing exceptions

When we re-source shipment requests, the shipping charges behaviour may change:

  • onFirst—The shipping line is assigned to the first generated shipment request:
    • If there is a line that can be shipped or assigned, the shipping charges remain in the original generated shipment request.
    • If the original shipping line is not cancelled, the shipping charges remains as is.
  • onLast—The shipping line is assigned to the last generated shipment request. If there is a line that can be shipped, the shipping charges are assigned to the last generated shipment request.

See the Re-sourcing topic for more information.

Specify Shipping charges in the customer_shipment_done message

To override the default behavior of Magento Commerce (MC), which just charges the shipping costs on the first invoice, this new shipping element indicates on which invoice it should charge the shipping costs.

To add detailed shipping charges to the magento.logistics.fulfillment_management.customer_shipment_done message:

  1. Ensure you are assigned the correct permissions to access this configuration and functionality.
  2. Navigate to Config > Global Settings > Order in your SI Portal.

  3. Enable the Display shipping charges in customer shipment done message configuration:

    Shipping charges

Once this configuration is enabled, the magento.logistics.fulfillment_management.customer_shipment_done message will include a shipping element for that shipment request.

Example of a magento.logistics.fulfillment_management.customer_shipment_done message with shipping charges enabled

{
   "shipment":{
      "shipment_id":"174",
      "shipment_request_id":"DECO233-cdp-final-000000044-01",
      "store_id":"DECO233",
      "order_id":"cdp-final-000000044",
      "source_id":"SOURCE-2",
      "method":"STANDARD",
      "shipment_date":"2020-04-02T12:54:42+00:00",
      "shipping":{
         "net_amount":10,
         "gross_amount":10,
         "tax_amount":0,
         "tax_rate":0,
         "taxes":[
            {
               "type":"NO TAX",
               "amount":0,
               "rate":0
            }
         ],
         "currency":"USD"
      }
   },
   "items":[
      {
         "order_line_id":"59",
         "order_line_number":1,
         "item_type":"PHYSICAL",
         "sku":"SKU002",
         "name":"Toy Car",
         "custom_details":[
            {
               "name":"imageUrl",
               "value":"http:\/\/localhost:8888\/pub\/media\/catalog\/product\/t\/o\/toy-car_2.jpg"
            }
         ],
         "image_url":"http:\/\/localhost:8888\/pub\/media\/catalog\/product\/t\/o\/toy-car_2.jpg",
         "order_line_price":{
            "net_amount":25.99,
            "gross_amount":25.99,
            "tax_amount":0,
            "tax_rate":0,
            "taxes":[
               {
                  "type":"NO TAX",
                  "amount":0,
                  "rate":0
               }
            ],
            "currency":"USD"
         },
         "order_line_promotions_info":{
            "original_price":25.99,
            "promotions":[

            ]
         },
         "status":"SHIPPED",
         "status_reason":"OSREPORT",
         "status_date":"2020-04-02T12:54:42+00:00"
      }
   ],
   "packages":[
      {
         "details":[

         ],
         "items":[
            1
         ],
         "aggregated_items":[
            {
               "aggregated_line_id":"1",
               "sku":"SKU002",
               "quantity":1,
               "order_lines":[
                  1
               ]
            }
         ],
         "carrier":"NOT AVAILABLE",
         "tracking_number":"NOT AVAILABLE",
         "tracking_link":"NOT AVAILABLE",
         "tracking_comment":"NOT AVAILABLE",
         "custom_attributes":[

         ]
      }
   ],
   "address":{
      "reference":"76",
      "address_type":"customer",
      "first_name":"Joe",
      "last_name":"Doe",
      "address1":"Street on Main",
      "city":"Traverse City",
      "state":"MI",
      "zip":"49684",
      "country_code":"US",
      "phone":"61616161616",
      "email":"yourid@youremail.com",
      "custom_attributes":[

      ]
   }
}

Home Delivery or Ship from Store processes

For Home delivery (HD) or Ship from Store (SFS) processes you can change the shipping address information during the order flow cycle until any of the order lines, as part of the shipment request, are sent to the logistics provider. If you want to add a UI restriction, search by using the service specification, magento.logistics.shipment_request_repository, in a shipment request.

This functionality is not applicable for ISPU processes.

Integration

To modify a shipping address or method use the following specifications, such as the update_shipping_address message.

Example of an update message.

{
    "jsonrpc" : "2.0",
    "method": "magento.sales.order_management.update_shipping_address",
    "params": {
 "shipping_address_modification": {
   "sales_channel_id": "ST1",
   "order_id": "xxxxx",
       "line_number": "5",
   "user": "string",
   "new_shipping_address": {
     "reference": "1234",
     "first_name": "string",
     "last_name": "string",
     "company_name": "string",
     "address1": "string",
     "address2": "string",
     "city": "string",
     "state": "string",
     "zip": "55678",
     "country_code": "string",
     "phone": "string",
     "email": "string",
     "latitude": "",
     "longitude": "",
     "custom_attributes": []
       {
         "name": "string",
         "value": "string"
       }
   }
 }
}
}
}

Example of a change line message.

{
    "jsonrpc": "2.0",
    "method": "magento.sales.order_management.update_shipping_line",
    "params": {
    "shipping_line_modification" : {
            "id": "000000257",
            "store": "ST1",
            "line_number" : "1",
            "new_shipping_line" : "3"
    }}
}

Example of a create line message.

{
   "shipping_line_creation": {
       "sales_channel_id": "ST1",
       "order_id": "14",
       "user": "jcuerdo",
       "line_numbers": [
           4
       ],
       "shipping_method": "STANDARD",
       "shipping_address": {
           "first_name": "Manolita",
           "last_name": "costelo",
           "company_name": "",
           "address1": "6146 Honey Bluff Parkway",
           "address2": "",
           "city": "Calder",
           "state": "MI",
           "zip": "49628-7978",
           "country_code": "US",
           "phone": "5552293326",
           "email": "roni_cost@example.com",
           "custom_attributes": []
       }
   }
}

When the action is performed successfully, our system will generate an event that could be consumed by any integration, with the name shipping_address_updated and exactly the same content as the previous one.

As this request is a synchronous one, if a failure occurs you will see a response message listing the reason of the non-expected behavior.

Example of a failed change via integration

{
    "jsonrpc":"2.0",
    "id":1,
    "error": {
        "message":"Feature with name \u0027updateShippingAddress\u0027, is not enabled.",
        "code":-32602
    }
}
© 2024 Adobe. All rights reserved.