Menu

Shipping Options API Routes

A shipping option is a way of shipping an item to or from the customer.

During the checkout flow, the customer selects their preferred shipping option to receive their order.

These API routes allow customers to retrieve available shipping options for their context.

GET /store/shipping-options#

List Shipping Options for Cart

Retrieve a list of shipping options for a cart. The cart's ID is set in the required cart_id query parameter.

The shipping options also be sorted or paginated.

For a shipping option whose price_type is calculated, the returned amount isn't reliable, as its price is computed on the fly by the fulfillment provider. To retrieve its price, use the Calculate Shipping Option Price API route.

Authentication: none.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
cart_idstring
The ID of the cart to retrieve its shipping options.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
is_returnbooleanOptional
Whether the shipping option can be used for returns.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request examples

Responses

200 OK

shipping_optionsobject[]
The list of shipping options.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /store/shipping-options/{id}/calculate#

Calculate Shipping Option Price

Calculate the price of a shipping option in a cart. Use this API route for shipping options whose price_type is calculated, as their price isn't stored but computed on the fly by the associated fulfillment provider against the cart.

If the fulfillment provider fails to calculate the price, this route returns an error.

Authentication: none.

Path parameters

idstring
The shipping option's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US
fieldsstringOptional
Comma-separated fields that should be included in the returned data. If a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. Without prefix it will replace the entire default fields.

Request body (application/json)

cart_idstring
The ID of the cart the shipping option is used in.
dataobjectOptional
Custom data that's useful for the fulfillment provider to calculate the price.

Request examples

Responses

200 OK

shipping_optionobject
The shipping option's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page