> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/admin/shipping-options/attribute-based-shipping-options/list-attribute-based-shipping-options.md).

# List attribute based shipping options

Returns a paginated list of attribute based shipping options, including inactive ones. Each entry contains the rule and calculator stored on the record together with the linked shipping option as a nested object.

```json
{"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"tags":[{"name":"Attribute Based Shipping Options","description":"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.\n\nEach 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](https://docs.akinon.com/technical-guides/commerce/shipping-rules-calculator) technical guide.\n\nRecords 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`.\n\n## Core Capabilities\n\n**1. Listing & Filtering**\n* Retrieve a paginated list of attribute based shipping options.\n* Filter by identifier, name, linked shipping option, active status, sort order, and creation or modification timestamp.\n* 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.\n\n**2. Full CRUD**\n* Create a record by linking a shipping option to a rule and a calculator.\n* Fully or partially update an existing record.\n* 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.\n\n## Read and Write Representations\n\nThe `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.\n\nThe 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](https://docs.akinon.com/technical-guides/commerce/shipping-rules-calculator) 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.\n\n## Dynamic Settings & Environment Variables\n\nThe 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**.\n\n| Key | Type | Default | Effect |\n|-----|------|---------|--------|\n| `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. |\n| `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. |\n| `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. |\n| `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. |\n| `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`. |\n\n**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."}],"servers":[{"description":"Omnitron Remote Proxy (external access — recommended)","url":"https://{omnitron_url}/api/v1/remote/{channel_id}","variables":{"omnitron_url":{"default":"sandbox.akinon.com","description":"Omnitron server URL (e.g., {omnitron.akinon.com})"},"channel_id":{"default":"1","description":"The channel identifier the remote request is routed through"}}},{"description":"Commerce API Server (internal / direct access only)","url":"https://{commerce_url}/api/v1","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Internal commerce server URL, reachable only from within the Omnitron network"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token credential sent in the Authorization header, in the form: `Token <your-token>`. Requires a staff (admin) account."}},"parameters":{"page":{"name":"page","in":"query","required":false,"description":"The page number to return.","schema":{"type":"integer","default":1}},"limit":{"name":"limit","in":"query","required":false,"description":"The number of items to return per page.","schema":{"type":"integer","default":10}},"sort":{"name":"sort","in":"query","required":false,"description":"Orders the results by one or more fields. Separate multiple fields with commas. Prefix a field with a hyphen (`-`) for descending order.","schema":{"type":"string"}}},"schemas":{"PaginatedAttributeBasedShippingOptionList":{"type":"object","description":"A paginated list of attribute based shipping options.","properties":{"count":{"type":"integer","description":"Total number of attribute based shipping options matching the query."},"next":{"type":["string","null"],"format":"uri","description":"URL of the next page, or `null` if this is the last page."},"previous":{"type":["string","null"],"format":"uri","description":"URL of the previous page, or `null` if this is the first page."},"results":{"type":"array","description":"The attribute based shipping options on the current page.","items":{"$ref":"#/components/schemas/AttributeBasedShippingOption"}}}},"AttributeBasedShippingOption":{"type":"object","description":"An attribute based shipping option returned by the API.","properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique identifier of the attribute based shipping option."},"name":{"type":["string","null"],"maxLength":128,"description":"Descriptive name of the record, used to tell apart several records that reuse the same shipping option."},"is_active":{"type":"boolean","description":"Whether the record is active. Only active records are evaluated at checkout.","default":true},"calculator":{"type":"object","description":"Calculator configuration. Determines how the shipping cost of a matched item group is computed, overriding the calculator of the linked shipping option.\n\nThe object must contain at minimum a `slug` key identifying the calculator. See the [Shipping Rules & Calculators guide](https://docs.akinon.com/technical-guides/commerce/shipping-rules-calculator) for available calculators and their parameters."},"rule":{"type":"object","description":"Rule configuration. Determines which item groups this option is offered for, overriding the rule of the linked shipping option.\n\nThe object contains a `slug` key identifying the rule. Records created with an empty rule are stored with the \"any rule\", which makes the option eligible for every group."},"sort_order":{"type":"integer","description":"Sort order used when evaluating records at checkout. Lower values are evaluated first.","default":0},"shipping_option":{"$ref":"#/components/schemas/AttributeBasedShippingOptionNestedShippingOption"}},"required":["pk","name","is_active","calculator","rule","sort_order","shipping_option"]},"AttributeBasedShippingOptionNestedShippingOption":{"type":"object","description":"The shipping option linked to an attribute based shipping option, as returned on read.\n\nThe linked shipping option's own `calculator` and `rule` are deliberately omitted: the ones stored on the attribute based record are the ones that apply.","properties":{"pk":{"type":"integer","readOnly":true,"description":"Unique identifier of the shipping option."},"name":{"type":"string","description":"Display name. Returned in the active request language, falling back to the default language."},"slug":{"type":"string","description":"URL-friendly unique identifier."},"is_active":{"type":"boolean","description":"Whether the shipping option itself is active."},"sort_order":{"type":"integer","description":"Sort order of the shipping option."},"description":{"type":["string","null"],"description":"Optional description of the shipping option."},"kwargs":{"$ref":"#/components/schemas/ShippingOptionKwargs"},"delivery_type":{"oneOf":[{"$ref":"#/components/schemas/ShippingOptionDeliveryTypeDetail"},{"type":"null"}],"description":"Delivery type of the shipping option."}}},"ShippingOptionKwargs":{"type":"object","description":"Extra configuration for the shipping option.\n\n`required_fields` lists the keys that must be present in the checkout data when an order is created with this shipping option. At order creation time, the values for those keys are copied from the checkout data into `Order.extra_field`.","properties":{"required_fields":{"type":"array","description":"List of field keys that must be present in the checkout data.","items":{"type":"string"}}}},"ShippingOptionDeliveryTypeDetail":{"type":"object","description":"Read representation of a delivery type — includes the raw enum value and its human-readable label.","properties":{"value":{"type":"string","description":"Enum value."},"label":{"type":"string","description":"Human-readable label for the delivery type."}}},"Error":{"type":"object","description":"An error response.","properties":{"detail":{"type":"string","description":"A human-readable description of the error."}},"additionalProperties":true}},"responses":{"Unauthorized":{"description":"Authentication credentials were not provided or are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The authenticated user does not have administrator privileges.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/attribute_based_shipping_options/":{"get":{"tags":["Attribute Based Shipping Options"],"operationId":"listAttributeBasedShippingOptions","summary":"List attribute based shipping options","description":"Returns a paginated list of attribute based shipping options, including inactive ones. Each entry contains the rule and calculator stored on the record together with the linked shipping option as a nested object.","parameters":[{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"name":"pk","in":"query","description":"Filter by the exact identifier of an attribute based shipping option.","required":false,"schema":{"type":"integer"}},{"name":"pk__in","in":"query","description":"Filter by a comma-separated list of identifiers. Returns only records whose identifier is in the list.","required":false,"schema":{"type":"string"}},{"name":"name","in":"query","description":"Filter by name. Case-insensitive partial match. Send `NULL_VALUE` to return only records without a name, or `NOT_NULL_VALUE` to return only records that have one.","required":false,"schema":{"type":"string"}},{"name":"shipping_option","in":"query","description":"Filter by the identifier of the linked shipping option.","required":false,"schema":{"type":"integer"}},{"name":"is_active","in":"query","description":"Filter by active status.","required":false,"schema":{"type":"boolean"}},{"name":"sort_order","in":"query","description":"Filter by exact sort order value.","required":false,"schema":{"type":"integer"}},{"name":"created_date","in":"query","description":"Filter by the exact creation timestamp.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"modified_date","in":"query","description":"Filter by the exact last-modification timestamp.","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"A page of attribute based shipping options.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedAttributeBasedShippingOptionList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.akinon.com/commerce-openapis/admin/shipping-options/attribute-based-shipping-options/list-attribute-based-shipping-options.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
