> 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/data-source-shipping-options.md).

# Data Source Shipping Options

Administrative endpoints for **data source shipping options** — per-seller delivery methods. Each record binds one shipping option to one data source (seller/warehouse) and gives that pairing its own **calculator** (how the shipping cost is computed) and **rule** (which baskets are eligible). This is what lets two sellers offer the same named delivery method at different prices or under different conditions. 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.

A shipping option can be bound to a given data source only once: the combination of `shipping_option` and `data_source` must be unique. Creating a second record for a pairing that already exists returns a validation error, so update the existing binding instead.

### Core Capabilities

**1. Listing & Filtering**

* Retrieve a paginated list of data source shipping options.
* Filter by identifier, by the shipping option or data source being bound, by active status, sort order, description, and creation or modification timestamp.
* Order results with the `sort` parameter, which accepts the fields of the record itself: `pk`, `is_active`, `sort_order`, `shipping_option`, `data_source` and `description`.

**2. Full CRUD**

* Bind a shipping option to a data source with its own calculator and rule.
* Fully or partially update an existing binding.
* Deactivate a binding: the `DELETE` method performs a **soft delete** — it sets `is_active` to `false` and keeps the record, so a binding can be taken out of checkout and brought back later without losing its configuration.

### Nested Objects in Responses

Requests reference the shipping option and the data source by their identifiers, but responses expand both into objects:

| Field             | On write                                   | On read                                                                                                                                                                                                          |
| ----------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shipping_option` | Identifier of the shipping option to bind. | The shipping option object, returned in the default language of the installation. Its own `calculator` and `rule` are **omitted**, because at checkout the calculator and rule of this binding are used instead. |
| `data_source`     | Identifier of the data source to bind.     | A compact reference to the data source: its identifier, name, title, slug and active status. Use the data source endpoints for the seller's full commercial and contact details.                                 |

### Checkout-Time Behaviour

Only bindings with `is_active` set to `true` are considered at checkout, and they are evaluated in ascending `sort_order`. For each data source represented in the basket, the eligible bindings are filtered by their rule and priced by their calculator. Give every data source at least one active binding whose rule accepts any basket, so that each seller in the basket always has a delivery method to offer.

### Dynamic Settings & Environment Variables

The following dynamic settings do not change the behaviour of the administrative CRUD endpoints themselves — every setting below is read at checkout time. They determine whether the records managed here are used at all, and how their cost is calculated.

| Key                                       | Type                    | Default                         | Effect                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------------- | ----------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE` | string (choice)         | `"ShippingOptionSelectionPage"` | Selects the checkout shipping flow. Set it to `"DataSourceShippingOptionSelectionPage"` to have the records managed here drive shipping selection at checkout; the other flows use their own configuration instead. Other values: `"ShippingOptionSelectionPage"`, `"AttributeBasedShippingOptionSelectionPage"`, `"RemoteShippingOptionSelectionPage"`. |
| `USE_EXTERNAL_COST_CALCULATOR`            | boolean                 | `false`                         | Applies only to bindings whose `calculator` is the remote cost calculator (`remote-cost-calculator`). When `true`, that calculator requests the shipping cost from the external service configured by `EXTERNAL_COST_CALCULATOR` instead of the platform's own cost service. Bindings using any other calculator are unaffected.                         |
| `EXTERNAL_COST_CALCULATOR`                | object `{host, token?}` | `{}`                            | Connection details for the external cost calculator: `host` (required) and `token` (optional). Only consulted when `USE_EXTERNAL_COST_CALCULATOR` is `true`.                                                                                                                                                                                             |

The remote cost calculator keeps checkout resilient: if the service it is configured against is unreachable, it applies the fallback amount defined in its own configuration so that the customer can still complete the order.

The settings `USE_BASKET_ITEM_ATTRIBUTES_FOR_ATTRIBUTE_BASED_SHIPPING`, `ATTRIBUTE_KEYS_FOR_ATTRIBUTE_BASED_SHIPPING_OPTION`, `REMOTE_SHIPPING_OPTION_PROVIDER` and `CHECKOUT_RETAIL_STORE_FILTERS` (described in the parent **Shipping Options** section) belong to other checkout selection flows or to store selection, and have no effect on the records managed here.

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


---

# 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/data-source-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.
