Selecting a shipping method
How to select a shipping method for each of the order shipments
Problem
You have a pending order and you want to give your customer the possibility to select a shipping method for each of the order shipments, based on its cost and delivery lead time.
Solution
Within Commerce Layer, an order can have many shipments and each shipment must have a valid shipping method before the order can be placed. To let the customer select a shipping method, first you need to get the list of available shipping methods for the order shipments and display them to the customer along with their delivery lead times. Then you can associate the selected shipping method with the shipment and eventually display its delivery lead time. To do that:
Send a
GET
request to the/api/orders/:id/shipments
endpoint, including the associatedavailable_shipping_methods
andstock_location
.Send a
GET
request to the/api/orders/delivery_lead_times
, including the associatedshipping_method
andstock_location
, and add some front-end logic to determine which of the returned delivery lead times is associated with a stock location that matches the one associated with the shipment.Send a
PATCH
request to the/api/shipments/:id
endpoint, setting itsshipping_method
relationship.Send a
GET
request to the/api/shipments/:id endpoint
, including the associatedshipping_method
anddelivery_lead_time
.
Including the stock location in the API calls above is necessary to be able to display the correct delivery lead time, especially if the order is split into many shipments.
Example
1. Get the available shipping methods
The following request retrieves the list of available shipping methods associated with the shipments of the order identified by the "NgojhKoyYN" ID:
2. Displaying the available shipping methods delivery lead times
The following request retrieves the list of the delivery lead times for the market in scope:
For performance reasons and to minimize the number of calls to the API, at this point you need to add the necessary logic to determine which of the returned delivery lead times has to be displayed for each shipping method on the front-end. Basically, it's all about — for each one of the available shipping methods associated with each shipment — filtering the returned delivery lead times to find which one is associated with a stock location that matches the stock location associated with the shipment.
The image below shows which specific attribute of the shipping method and delivery lead time object has to be displayed.
For performance reasons, in the response of both the above calls (1. and 2.) the price of the shipping methods whose cost is supposed to be provided by an external service (if any) is not updated with the value calculated externally which is fetched only when the shipping method is selected.
3. Select a shipping method
The following request associates the selected shipping method (identified by the "DEqjzFMykO" ID) with the shipment identified by the "kPzgnCjdQy" ID:
4. Displaying the selected shipping method delivery lead time
The following request retrieves the delivery lead time associated with the shipment identified by the "kPzgnCjdQy" ID:
The image below shows how the displayed information about the selected shipping method is mapped to specific relationships of the shipment object.
Additional notes
Purchasing gift cards
When purchasing digital products — i.e. gift cards — no shipments are created for the order, therefore the order can be placed without any shipping method.
More to read
See our documentation if you need more information about the shipping method, delivery lead time, and gift card objects or on how to update and retrieve a shipment or include associations.
Last updated