> 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/create-a-shipping-option.md).

# Create a shipping option

Creates a new shipping option.

The `slug` must be unique across all shipping options. If it already exists, the request fails.

To make the option eligible for all baskets, send `rule` as an empty object (`{}`); the server will apply `AnyRule` automatically.

```json
{"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"tags":[{"name":"Shipping Options","description":"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](https://docs.akinon.com/technical-guides/commerce/shipping-rules-calculator) technical guide.\n\n## Core Capabilities\n\n**1. Listing & Filtering**\n* 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.\n* Filter by identifier, slug, active status, and sort order; order results by any field using the `sort` parameter.\n\n**2. Full CRUD**\n* Create a shipping option with a name, slug, calculator, rule, and an optional delivery type.\n* Fully or partially update an existing option.\n* 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.\n\n## Delivery Types\n\nThe `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.\n\n| Value | Label |\n|-------|-------|\n| `standard` | Standard Delivery |\n| `same_day` | Same Day Delivery |\n| `next_day` | Next Day Delivery |\n| `in_store` | In-store Delivery |\n\n## Dynamic Settings & Environment Variables\n\nThe 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.\n\n| Key | Type | Default | Effect |\n|-----|------|---------|--------|\n| `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. |\n| `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`. |\n| `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\"`. |\n| `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\"`. |\n| `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\"`. |\n| `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\"`. |\n| `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. |\n\n**Environment variables:** No environment variables are read directly by these endpoints."}],"servers":[{"description":"Omnitron Remote Proxy (external access — recommended)","url":"https://{omnitron_url}/api/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."}},"schemas":{"ShippingOptionRequest":{"type":"object","description":"Fields for creating or updating a shipping option.","properties":{"name":{"type":"string","description":"Display name of the shipping option."},"slug":{"type":"string","description":"URL-friendly unique identifier. Must be unique across all shipping options."},"is_active":{"type":"boolean","description":"Whether the shipping option is active.","default":true},"calculator":{"type":"object","description":"Calculator configuration. The object must contain 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. The object must contain a `slug` key identifying the rule. Send `{}` to apply `AnyRule` (all baskets are eligible). See the [Shipping Rules & Calculators guide](https://docs.akinon.com/technical-guides/commerce/shipping-rules-calculator) for available rules and their parameters."},"sort_order":{"type":"integer","description":"Sort order. Lower values appear first.","default":0},"description":{"type":["string","null"],"description":"Optional description of the shipping option."},"kwargs":{"$ref":"#/components/schemas/ShippingOptionKwargs"},"delivery_type":{"oneOf":[{"$ref":"#/components/schemas/ShippingOptionDeliveryType"},{"type":"null"}],"description":"Delivery type of the shipping option."}},"required":["name","slug","calculator","rule"]},"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"}}}},"ShippingOptionDeliveryType":{"type":"string","description":"Delivery type of the shipping option.\n\n| Value | Description |\n|---|---|\n| `standard` | Standard delivery |\n| `same_day` | Same-day delivery |\n| `next_day` | Next-day delivery |\n| `cargo` | Cargo delivery |\n| `cargo_with_appointment` | Cargo delivery with scheduled appointment |\n| `store_pickup` | Click & collect from retail store |\n| `digital` | Digital / downloadable product delivery |","enum":["standard","same_day","next_day","cargo","cargo_with_appointment","store_pickup","digital"]},"ShippingOption":{"type":"object","description":"A shipping option returned by the API.","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 is active. Inactive options are hidden from the storefront.","default":true},"calculator":{"type":"object","description":"Calculator configuration. Determines how the shipping cost is computed.\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 baskets are eligible for this shipping option.\n\nThe object must contain a `slug` key identifying the rule. The `name` key is optional. Send `{}` to apply `AnyRule` (all baskets are eligible). See the [Shipping Rules & Calculators guide](https://docs.akinon.com/technical-guides/commerce/shipping-rules-calculator) for available rules and their parameters."},"sort_order":{"type":"integer","description":"Sort order used when listing options. Lower values appear first.","default":0},"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."}},"required":["pk","name","slug","is_active","calculator","rule","sort_order"]},"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."}}},"ValidationError":{"type":"object","description":"Returned when the request contains invalid or missing data. Errors are grouped by the field they apply to: each key is the name of a field from the request and its value is a list of one or more messages describing what is wrong with that field. Messages that do not belong to any single field are grouped under `non_field_errors`.","properties":{"non_field_errors":{"type":"array","description":"Error messages that apply to the request as a whole rather than to a specific field.","items":{"type":"string"}}},"additionalProperties":{"type":"array","description":"The list of error messages for the field named by the key.","items":{"type":"string"}}},"Error":{"type":"object","description":"An error response.","properties":{"detail":{"type":"string","description":"A human-readable description of the error."}},"additionalProperties":true}},"responses":{"ValidationError":{"description":"The request contains invalid or missing data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"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":{"/shipping_options/":{"post":{"tags":["Shipping Options"],"operationId":"createShippingOption","summary":"Create a shipping option","description":"Creates a new shipping option.\n\nThe `slug` must be unique across all shipping options. If it already exists, the request fails.\n\nTo make the option eligible for all baskets, send `rule` as an empty object (`{}`); the server will apply `AnyRule` automatically.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingOptionRequest"}}}},"responses":{"201":{"description":"The created shipping option.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingOption"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://apidocs.akinon.com/commerce-openapis/admin/shipping-options/create-a-shipping-option.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.