Shipping Options

Administrative endpoints for shipping options — the named delivery methods presented to customers at checkout. Each shipping option combines a calculator (how the shipping cost is computed) with a rule (which baskets or orders are eligible for this option). For the full list of available rule and calculator types with their fields and examples, see the Shipping Rules & Calculators technical guide.

Core Capabilities

1. Listing & Filtering

• Retrieve a paginated list of shipping options in the language active for the current request, falling back to the default language when no translation exists.

• Filter by identifier, slug, active status, and sort order; order results by any field using the sort parameter.

2. Full CRUD

• Create a shipping option with a name, slug, calculator, rule, and an optional delivery type.

• Fully or partially update an existing option.

• Deactivate a shipping option: the DELETE method performs a soft delete — it sets is_active to false and retains the record. Permanent removal is not available through this API.

Delivery Types

The delivery_type field describes the fulfilment method. Send the string value on create and update; on retrieval the field is returned as an object with value and label keys.

Value	Label
standard	Standard Delivery
same_day	Same Day Delivery
next_day	Next Day Delivery
in_store	In-store Delivery

Dynamic Settings & Environment Variables

The following dynamic settings affect the checkout-time evaluation of the shipping options managed here. They do not change the behaviour of the administrative CRUD endpoints themselves, but they determine which options become available to customers and how their cost is calculated.

Key	Type	Default	Effect
USE_EXTERNAL_COST_CALCULATOR	boolean	false	When true, cost calculation is delegated to the external service configured by EXTERNAL_COST_CALCULATOR instead of the built-in calculator.
EXTERNAL_COST_CALCULATOR	object {host, token?}	{}	Connection details for the external cost calculator: host (required URL) and token (optional bearer token). Only active when USE_EXTERNAL_COST_CALCULATOR is true.
CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE	string (choice)	"ShippingOptionSelectionPage"	Determines which shipping selection flow is active at checkout. Values: "ShippingOptionSelectionPage" (evaluates these records directly), "DataSourceShippingOptionSelectionPage", "AttributeBasedShippingOptionSelectionPage", "RemoteShippingOptionSelectionPage".
REMOTE_SHIPPING_OPTION_PROVIDER	object {klass, conf}	ExtensionShippingOptionProvider defaults	Provider class and connection configuration (base_url, username, password) used when CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE is "RemoteShippingOptionSelectionPage".
USE_BASKET_ITEM_ATTRIBUTES_FOR_ATTRIBUTE_BASED_SHIPPING	boolean	false	When true, basket item attributes take priority over product attributes in attribute-based shipping resolution. Relevant only for "AttributeBasedShippingOptionSelectionPage".
ATTRIBUTE_KEYS_FOR_ATTRIBUTE_BASED_SHIPPING_OPTION	array of objects	[]	Attribute key definitions (group_attribute_key, rule, sort_order) used to group basket items for attribute-based shipping. Relevant only for "AttributeBasedShippingOptionSelectionPage".
CHECKOUT_RETAIL_STORE_FILTERS	object {by_stock}	{by_stock: false}	When by_stock is true, only retail stores with available stock are shown at checkout.

Environment variables: No environment variables are read directly by these endpoints.