Introducing our brand new Rules Engine —
Read the docs
LogoLogo
Core APIOther APIsChangelog
How-tos
How-tos
  • Introduction
  • Product discovery
    • Product listing page
    • Product page
  • Placing orders
    • Shopping cart
      • Creating a shopping cart
      • Adding products to cart
      • Updating cart quantities
      • Removing products from cart
      • Displaying the cart summary
    • Checkout
      • Adding the customer
      • Adding a billing address
      • Adding a shipping address
      • Selecting a shipping method
      • Selecting a payment method
      • Adding a payment source
      • Adding a gift card or coupon
      • Placing the order
    • Subscriptions
      • Configuring a subscription model
      • Selecting the source order
      • Generating the subscriptions
      • Updating the subscriptions
    • Payments
      • Adyen
        • Adding the payment source
        • Sending back the payment details
        • Configuring the notification webhooks
        • Reusing the payment source
      • Axerve
        • Adding the payment source
        • Updating the payment intent
      • Braintree
        • Adding the payment source
        • Sending back the payment method nonce
        • Accepting local payments
        • Reusing the payment source
      • Checkout.com
        • Adding the payment source
        • Getting the payment details
        • Refreshing pending transactions
        • Reusing the payment source
      • Klarna
        • Adding the payment source
        • Sending back the authorization token
        • Reusing the payment source
      • PayPal
        • Adding the payment source
        • Preparing the payment for execution
      • Stripe
        • Adding the payment source
        • Refreshing the payment source
        • Reusing the payment source
      • Manual payments
        • Adding a wire transfer payment source
      • External payments
        • Adding the payment source
        • Reusing the payment source
    • Auto-capture
      • Enabling the auto-capture
      • Limiting the auto-capture amount
  • inventory
    • Inventory strategies
      • No split
      • Split shipments
      • Split by line items
      • Ship from first available (or primary)
      • Ship from primary
  • FAQ
    • Environments and initial setup
    • Authentication and access tokens
On this page
  • Problem
  • Solution
  • Example
  • Additional notes
  • More to read
  1. Placing orders
  2. Checkout

Selecting a shipping method

How to select a shipping method for each of the order shipments

PreviousAdding a shipping addressNextSelecting a payment method

Last updated 2 months ago

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:

  1. Send a GET request to the /api/orders/:id/shipments endpoint, including the associated available_shipping_methods and stock_location.

  2. Send a GET request to the /api/orders/delivery_lead_times, including the associated shipping_method and stock_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.

  3. Send a PATCH request to the /api/shipments/:id endpoint, setting its shipping_method relationship.

  4. Send a GET request to the /api/shipments/:id endpoint, including the associated shipping_method and delivery_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:

curl -g -X GET \
  'https://yourdomain.commercelayer.io/api/orders/NgojhKoyYN/shipments?include=available_shipping_methods,stock_location' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json'

On success, the API responds with a 200 OK status code, returning the list of shipment objects and the associated available shipping methods and stock locations:

{
  "data": [
    {
      "id": "kPzgnCjdQy",
      "type": "shipments",
      "links": {
        "self": "https://yourdomain.commercelayer.io/api/shipments/kPzgnCjdQy"
      },
      "attributes": {
        "number": "1234/S/001",
        "status": "upcoming",
        "currency_code": "EUR",
        "cost_amount_cents": 0,
        "cost_amount_float": 0.0,
        "formatted_cost_amount": "$0.00",
        "skus_count": 4,
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "metadata": {}
      },
      "relationships": {
        "order": {
          "links": {...}
        },
        "shipping_category": {
          "links": {...}
        },
        "stock_location": {
          "links": {...}
          "data": {
            "type": "stock_locations",
            "id": "DMzAouwyXk"
          }
        },
        "origin_address": {
          "links": {...}
        },
        "shipping_address": {
          "links": {...}
        },
        "shipping_method": {
          "links": {...}
        },
        "delivery_lead_time": {
          "links": {...}
        },
        "shipment_line_items": {
          "links": {...}
        },
        "stock_transfers": {
          "links": {...}
        },
        "available_shipping_methods": {
          "links": {...},
          "data": [
            {
              "type": "shipping_methods",
              "id": "WErDzFLeQN"
            },
            {
              "type": "shipping_methods",
              "id": "DEqjzFMykO"
            }
          ]
        },
        "carrier_accounts": {
          "links": {...}
        },
        "parcels": {
          "links": {...}
        },
        "attachments": {...}
        }
      },
      "meta": {
          "mode": "test"
      }
    }
  ],
  "included": [
    {
      "id": "DMzAouwyXk",
      "type": "stock_locations",
      "links": {...},
      "attributes": {
        "number": 1234,
        "name": "Primary Warehouse",
        "label_format": "PDF",
        "suppress_etd": null,
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "address": {
            "links": {...}
        },
        "inventory_stock_locations": {
            "links": {...}
        },
        "inventory_return_locations": {
            "links": {...}
        },
        "stock_items": {
            "links": {...}
        },
        "stock_transfers": {
            "links": {...}
        },
        "attachments": {
            "links": {...}
        }
      },
      "meta": {
          "mode": "test"
      }
    },
    {
      "id": "WErDzFLeQN",
      "type": "shipping_methods",
      "links": {
          "self": "https://yourdomain.commercelayer.io/api/shipping_methods/WErDzFLeQN"
      },
      "attributes": {
        "name": "Standard Shipping",
        "disabled_at": null,
        "currency_code": "EUR",
        "price_amount_cents": 700,
        "price_amount_float": 7.0,
        "formatted_price_amount": "€7,00",
        "free_over_amount_cents": 9900,
        "free_over_amount_float": 99.0,
        "formatted_free_over_amount": "€99,00",
        "price_amount_for_shipment_cents": 0,
        "price_amount_for_shipment_float": 0.0,
        "formatted_price_amount_for_shipment": "€0,00",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "metadata": {}
      },
      "relationships": {
        "market": {
          "links": {...}
        },
        "shipping_zone": {
          "links": {...}
        },
        "shipping_category": {
          "links": {...}
        },
        "delivery_lead_time_for_shipment": {
          "links": {...}
        },
        "attachments": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "id": "DEqjzFMykO",
      "type": "shipping_methods",
      "links": {
        "self": "https://yourdomain.commercelayer.io/api/shipping_methods/DEqjzFMykO"
      },
      "attributes": {
        "name": "Express Delivery",
        "disabled_at": null,
        "currency_code": "EUR",
        "price_amount_cents": 1200,
        "price_amount_float": 12.0,
        "formatted_price_amount": "€10,00",
        "free_over_amount_cents": null,
        "free_over_amount_float": null,
        "formatted_free_over_amount": null,
        "price_amount_for_shipment_cents": 1200,
        "price_amount_for_shipment_float": 12.0,
        "formatted_price_amount_for_shipment": "€12,00",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "metadata": {}
      },
      "relationships": {
        "market": {
          "links": {..}
        },
        "shipping_zone": {
          "links": {...}
        },
        "shipping_category": {
          "links": {...}
        },
        "delivery_lead_time_for_shipment": {
          "links": {...}
        },
        "attachments": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    }
  ],
  "meta": {
    "record_count": 1,
    "page_count": 1
  },
  "links": {
      "first": "https://yourdomain.commercelayer.io/api/orders/NgojhKoyYN/shipments?include=available_shipping_methods,stock_location&page[number]=1&page[size]=10",
      "last": "https://yourdomain.commercelayer.io/api/orders/NgojhKoyYN/shipments?include=available_shipping_methods,stock_location&page[number]=1&page[size]=10"
  }
}

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:

curl -g -X GET \
  'https://yourdomain.commercelayer.io/api/delivery_lead_times?include=shipping_method,stock_location' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json'

On success, the API responds with a 200 OK status code, returning the list of delivery lead time objects and the associated shipping methods and stock locations:

{
  "data": [
    {
      "id": "nOZwqFYXQB",
      "type": "delivery_lead_times",
      "links": {...},
      "attributes": {
        "min_hours": 72,
        "max_hours": 120,
        "min_days": 3,
        "max_days": 5,
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "stock_location": {
          "links": {...},
          "data": {
            "type": "stock_locations",
            "id": "DMzAouwyXk"
          }
        },
        "shipping_method": {
          "links": {...},
          "data": {
            "type": "shipping_methods",
            "id": "WErDzFLeQN"
          }
        },
        "attachments": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "id": "AxwloFjQbp",
      "type": "delivery_lead_times",
      "links": {...},
      "attributes": {
        "min_hours": 48,
        "max_hours": 72,
        "min_days": 2,
        "max_days": 3,
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "stock_location": {
          "links": {...},
          "data": {
            "type": "stock_locations",
            "id": "DMzAouwyXk"
          }
        },
        "shipping_method": {
          "links": {...},
          "data": {
            "type": "shipping_methods",
            "id": "DEqjzFMykO"
          }
        },
        "attachments": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "id": "vxRoAFeymp",
      "type": "delivery_lead_times",
      "links": {...},
      "attributes": {
        "min_hours": 96,
        "max_hours": 144,
        "mdin_days": 4,
        "max_days": 6,
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "stock_location": {
          "links": {...},
          "data": {
            "type": "stock_locations",
            "id": "enbqQuXVwM"
          }
        },
        "shipping_method": {
          "links": {...},
          "data": {
            "type": "shipping_methods",
            "id": "WErDzFLeQN"
          }
        },
        "attachments": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "id": "zBdZGFADkp",
      "type": "delivery_lead_times",
      "links": {...},
      "attributes": {
        "min_hours": 72,
        "max_hours": 96,
        "min_days": 3,
        "max_days": 4,
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "stock_location": {
          "links": {...},
          "data": {
            "type": "stock_locations",
            "id": "enbqQuXVwM"
          }
        },
        "shipping_method": {
          "links": {...},
          "data": {
            "type": "shipping_methods",
            "id": "DEqjzFMykO"
          }
        },
        "attachments": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    }
  ],
  "included": [
    {
      "id": "DMzAouwyXk",
      "type": "stock_locations",
      "links": {...},
      "attributes": {
        "number": 1234,
        "name": "Primary Warehouse",
        "label_format": "PDF",
        "suppress_etd": null,
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "address": {
          "links": {...}
        },
        "inventory_stock_locations": {
          "links": {...}
        },
        "inventory_return_locations": {
          "links": {...}
        },
        "stock_items": {
          "links": {...}
        },
        "stock_transfers": {
          "links": {...}
        },
        "attachments": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "id": "enbqQuXVwM",
      "type": "stock_locations",
      "links": {...},
      "attributes": {
        "number": 2345,
        "name": "Backorder Warehouse",
        "label_format": "PDF",
        "suppress_etd": null,
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "address": {
          "links": {...}
        },
        "inventory_stock_locations": {
          "links": {...}
        },
        "inventory_return_locations": {
          "links": {...}
        },
        "stock_items": {
          "links": {...}
        },
        "stock_transfers": {
          "links": {...}
        },
        "attachments": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "id": "WErDzFLeQN",
      "type": "shipping_methods",
      "links": {...},
      "attributes": {
        "name": "Standard Shipping",
        "disabled_at": null,
        "currency_code": "EUR",
        "price_amount_cents": 700,
        "price_amount_float": 7.0,
        "formatted_price_amount": "€7,00",
        "free_over_amount_cents": 9900,
        "free_over_amount_float": 99.0,
        "formatted_free_over_amount": "€99,00",
        "price_amount_for_shipment_cents": 700,
        "price_amount_for_shipment_float": 7.0,
        "formatted_price_amount_for_shipment": "€7,00",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "market": {
          "links": {...}
        },
        "shipping_zone": {
          "links": {...}
        },
        "shipping_category": {
          "links": {...}
        },
        "delivery_lead_time_for_shipment": {
          "links": {...}
        },
        "attachments": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "id": "DEqjzFMykO",
      "type": "shipping_methods",
      "links": {...},
      "attributes": {
        "name": "Express Delivery",
        "disabled_at": null,
        "currency_code": "EUR",
        "price_amount_cents": 1200,
        "price_amount_float": 12.0,
        "formatted_price_amount": "€12,00",
        "free_over_amount_cents": null,
        "free_over_amount_float": null,
        "formatted_free_over_amount": null,
        "price_amount_for_shipment_cents": 1200,
        "price_amount_for_shipment_float": 12.0,
        "formatted_price_amount_for_shipment": "€12,00",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "market": {
          "links": {...}
        },
        "shipping_zone": {
          "links": {...}
        },
        "shipping_category": {
          "links": {...}
        },
        "delivery_lead_time_for_shipment": {
          "links": {...}
        },
        "attachments": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    }
  ],
  "meta": {
    "record_count": 4,
    "page_count": 1
  },
  "links": {
    "first": "https://yourdomain.commercelayer.io/api/delivery_lead_times?include=shipping_method,stock_location&page[number]=1&page[size]=10",
    "last": "https://yourdomain.commercelayer.io/api/delivery_lead_times?include=shipping_method,stock_location&page[number]=1&page[size]=10"
  }
}

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.

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:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/shipments/kPzgnCjdQy' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "shipments",
      "id": "kPzgnCjdQy",
      "relationships": {
        "shipping_method": {
          "data": {
            "type": "shipping_methods",
            "id": "DEqjzFMykO"
          }
        }
      }
    }
  }'

On success, the API responds with a 200 OK status code, returning the updated shipment object:

{
  "data": {
    "id": "kPzgnCjdQy",
    "type": "shipments",
    "links": {
        "self": "https://yourdomain.commercelayer.io/api/shipments/kPzgnCjdQy"
    },
    "attributes": {
      "number": "1234/S/001",
      "status": "upcoming",
      "currency_code": "EUR",
      "cost_amount_cents": 0,
      "cost_amount_float": 0.0,
      "formatted_cost_amount": "$0.00",
      "skus_count": 4,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "metadata": {}
    },
    "relationships": {
      "order": {
        "links": {...}
      },
      "shipping_category": {
        "links": {...}
      },
      "stock_location": {
        "links": {...}
      },
      "shipping_address": {
        "links": {...}
      },
      "shipping_method": {
        "links": {...}
      },
      "shipment_line_items": {
        "links": {...}
      },
      "available_shipping_methods": {
        "links": {...}
      },
      "parcels": {
        "links": {...}
      },
      "attachments": {
        "links": {...}
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

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:

curl -g -X GET \ 
  'https://yourdomain.commercelayer.io/api/shipments/kPzgnCjdQy?include=shipping_method,delivery_lead_time' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json'

On success, the API responds with a 200 OK status code, returning the selected shipment object, together with the associated shipping method and delivery lead time:

{
  "data": {
    "id": "kPzgnCjdQy",
    "type": "shipments",
    "links": {...},
    "attributes": {
      "number": "1234/S/001",
      "status": "upcoming",
      "currency_code": "EUR",
      "cost_amount_cents": 0,
      "cost_amount_float": 0.0,
      "formatted_cost_amount": "$0.00",
      "skus_count": 5,
      "rates": [],
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "order": {
        "links": {...}
      },
      "shipping_category": {
        "links": {...}
      },
      "stock_location": {
        "links": {...}
      },
      "origin_address": {
        "links": {...}
      },
      "shipping_address": {
        "links": {...}
      },
      "shipping_method": {
        "links": {...},
        "data": {
          "type": "shipping_methods",
          "id": "DEqjzFMykO"
        }
      },
      "delivery_lead_time": {
        "links": {...},
        "data": {
          "type": "delivery_lead_times",
          "id": "AxwloFjQbp"
        }
      },
      "shipment_line_items": {
        "links": {...}
      },
      "stock_transfers": {
        "links": {...}
      },
      "available_shipping_methods": {
        "links": {...}
      },
      "carrier_accounts": {
        "links": {...}
      },
      "parcels": {
        "links": {...}
      },
      "attachments": {
        "links": {...}
      }
    },
    "meta": {
      "mode": "test"
    }
  },
  "included": [
    {
      "id": "DEqjzFMykO",
      "type": "shipping_methods",
      "links": {...},
      "attributes": {
        "name": "Express Delivery",
        "disabled_at": null,
        "currency_code": "EUR",
        "price_amount_cents": 1200,
        "price_amount_float": 12.0,
        "formatted_price_amount": "€7,00",
        "free_over_amount_cents": null,
        "free_over_amount_float": null,
        "formatted_free_over_amount": null,
        "price_amount_for_shipment_cents": 1200,
        "price_amount_for_shipment_float": 12.0,
        "formatted_price_amount_for_shipment": "€12,00",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "market": {
          "links": {...}
        },
        "shipping_zone": {
          "links": {...}
        },
        "shipping_category": {
          "links": {...}
        },
        "delivery_lead_time_for_shipment": {
          "links": {...}
        },
        "attachments": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "id": "AxwloFjQbp",
      "type": "delivery_lead_times",
      "links": {...},
      "attributes": {
        "min_hours": 48,
        "max_hours": 72,
        "min_days": 2,
        "max_days": 3,
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "stock_location": {
          "links": {...}
        },
        "shipping_method": {
          "links": {...}
        },
        "attachments": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test"
      }
    }
  ]
}

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.

Default shipping method

More to read

For performance reasons, in the response of both the above calls ( and ) the price of the shipping methods whose cost is supposed to be provided (if any) is not updated with the value calculated externally which is fetched only when the shipping method is .

If you set a , all the shipments that belong to the market's orders and that are not already associated with a shipping method will be automatically associated with the default one. In particular, any new shipment will be automatically associated with the default shipping method at creation time and the default shipping method will be listed among the . Of course, you can always change the shipping method by and updating the relationship.

See our documentation if you need more information about the , , and objects or on how to and or .

shipping method
delivery lead time
gift card
update
retrieve a shipment
include associations
1.
2.
selected
by an external service
shipment's available shipping methods
patching the shipment
default shipping method for a market
A sample shipping method selection
A sample available shipping methods delivery lead times mapping
A sample selected shipping method delivery lead times mapping