Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 sort parameter 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 DELETE method performs a soft delete — it sets is_active to false and 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.

Key
Type
Default
Effect

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?