Attribute Based Shipping Options
Administrative endpoints for attribute based shipping options — shipping options that are offered per group of basket items rather than per basket. At checkout the basket is split into groups according to a configured product attribute (for example a vendor, a warehouse or a delivery-promise attribute), and each group is then offered its own shipping option and charged its own shipping cost.
Each record links an existing shipping option to a rule (which item groups the option is eligible for) and a calculator (how the shipping cost of that group is computed). The rule and calculator configured here take precedence over the ones on the linked shipping option itself, so the same shipping option can be reused with different eligibility and pricing per attribute group. For the full list of available rule and calculator types with their fields and examples, see the Shipping Rules & Calculators technical guide.
Records are only consulted at checkout when the attribute-based shipping flow is the active shipping selection flow (see Dynamic Settings & Environment Variables below). Only active records are evaluated, in ascending sort_order.
Core Capabilities
1. Listing & Filtering
Retrieve a paginated list of attribute based shipping options.
Filter by identifier, name, linked shipping option, active status, sort order, and creation or modification timestamp.
Order results with the
sortparameter by identifier, name, active status, sort order, calculator, rule or linked shipping option. Sorting by the creation or modification timestamp is not supported; such a value is ignored and the default ordering is kept.
2. Full CRUD
Create a record by linking a shipping option to a rule and a calculator.
Fully or partially update an existing record.
Deactivate a record: the
DELETEmethod performs a soft delete — it setsis_activetofalseand retains the record. Permanent removal is not available through this API.
Read and Write Representations
The shipping_option field is asymmetric: send the identifier of an existing shipping option when creating or updating, and receive the full shipping option as a nested object on read. The nested object deliberately omits the shipping option's own calculator and rule, because the ones stored on the attribute based record are what apply.
The contents of calculator and rule are stored exactly as sent and are not checked against the available calculator and rule types when the record is created or updated. An unrecognised or incomplete configuration is therefore accepted here but cannot be applied at checkout, so verify the values against the Shipping Rules & Calculators guide before sending them. A completely empty calculator ({}) is the one exception: it falls back to the default discount based calculator, which adds no shipping cost.
Dynamic Settings & Environment Variables
The dynamic settings below do not change the behaviour of these administrative CRUD endpoints — every record can be created, listed and updated regardless of how they are set. They determine whether and how the records managed here are used at checkout.
CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE
string (choice)
"ShippingOptionSelectionPage"
Must be set to "AttributeBasedShippingOptionSelectionPage" for the records managed here to be used at checkout. With any other value ("ShippingOptionSelectionPage", "DataSourceShippingOptionSelectionPage", "RemoteShippingOptionSelectionPage") these records are stored but never evaluated.
ATTRIBUTE_KEYS_FOR_ATTRIBUTE_BASED_SHIPPING_OPTION
array of objects
[]
The attribute keys used to split a basket into groups, each entry holding a group_attribute_key, an optional rule and a sort_order. While this list is empty no grouping takes place, so no record managed here can be matched to a group.
USE_BASKET_ITEM_ATTRIBUTES_FOR_ATTRIBUTE_BASED_SHIPPING
boolean
false
When true, attributes set on the basket item take priority over the product's own attributes while grouping and while evaluating product-attribute rules. Keep it false when customers can change basket item attributes and those changes should not influence which shipping option is offered.
USE_EXTERNAL_COST_CALCULATOR
boolean
false
When true, the shipping cost of each group is obtained from the external service configured by EXTERNAL_COST_CALCULATOR instead of the calculator stored on the record.
EXTERNAL_COST_CALCULATOR
object {host, token?}
{}
Connection details for that external service: host (required URL) and token (optional bearer token). Only consulted when USE_EXTERNAL_COST_CALCULATOR is true.
Environment variables: No environment variables are read directly by these endpoints. The defaults of USE_EXTERNAL_COST_CALCULATOR and EXTERNAL_COST_CALCULATOR can be seeded from the deployment configuration, after which the stored dynamic setting takes over.
Last updated
Was this helpful?

