This page lists every field available when creating or editing a Shipping Option. Use it when you need to understand what a specific field controls, what its allowed values are, or how it interacts with pricing and rules. For a guided setup walkthrough, see the Shipping Options core concepts page.
| Field | Type | Default | Description |
|---|
name | Text | — | The display name shown to customers in checkout. Keep it short and recognisable, e.g., "Home Delivery" or "Parcel Locker". |
description | Text | — | A subtitle shown below the option name in checkout. Use it to add context, e.g., "Delivered to your door within 2–4 working days". |
service_code | Text | Auto-derived | A machine-readable identifier for this option. Auto-generated from name if left blank. Used in rules, API responses, and integrations. |
enabled | Boolean | true | When false, the method is fully disabled and never appears in checkout regardless of rules. Use to temporarily deactivate a method without deleting it. |
hidden | Boolean | false | When true, the method is hidden by default and only appears when an enable_method rule fires. Use for B2B-only or conditional options that should not be visible to all customers. |
position | Integer | — | Display sort order. Options with lower position numbers appear earlier in the checkout list. |
stop_after_first_match | Boolean | false | When true, rule evaluation stops after the first matching rule fires. When false, all matching rules are applied in priority order. |
notes | Text | — | Internal notes visible only to your team in the Shipit admin. Not shown to customers. |
delivery_checkout_configuration_id | Reference | — | The Checkout Setup this option belongs to. An option only appears in checkouts served by the linked setup. |
shipit_service_id | Reference | — | The underlying carrier service from Shipit's carrier catalog. Links the option to a real carrier product. |
carrier_code | Read-only | — | Populated automatically from shipit_service_id. The short code identifying the carrier (e.g., postnord, dhl). |
carrier_name | Read-only | — | Populated automatically from shipit_service_id. The human-readable carrier name. |
tags | Array of strings | — | Internal labels for organising options, e.g., ["express", "b2b"]. Not shown to customers. |
| Field | Type | Default | Description |
|---|
base_price | Decimal | — | The price charged when no pricing tier matches the cart. Acts as the catch-all price. |
currency | Select | — | ISO 4217 currency code, e.g., EUR, SEK, NOK, DKK. |
pricing_tiers | Array | — | Weight-based price steps. Each tier defines a weight threshold in grams and a corresponding price. The lowest matching tier is applied. |
show_rebate | Boolean | false | When enabled, displays a crossed-out "was" price alongside the actual price. Requires regular_fee to be set. |
regular_fee | Decimal | — | The "was" price displayed when show_rebate is on. Display-only — does not affect the amount charged. |
use_free_delivery_label | Boolean | false | When enabled and the calculated price is zero, displays a text label instead of "0.00". |
free_delivery_label | Text | FREE | The label shown when use_free_delivery_label is on and the price is zero. |
free_delivery_labels_by_provider | Object | — | Per-provider overrides for the free delivery label. Keys are provider codes; values are the label strings. |
tax_strategy | Select | — | How the tax rate is determined. checkout_configuration_market — derive rate from the market of this checkout setup. destination_country — derive rate from the destination country. custom — use the rate in tax_rate. |
tax_rate | Decimal | — | Tax percentage (0–100). Only used when tax_strategy is custom. |
tax_included | Boolean | false | When enabled, prices entered are VAT-inclusive. When disabled, tax is calculated on top. |
pricing_currency_display | Select | symbol | symbol — show currency symbol (€). code — show ISO code (EUR). |
pricing_currency_position | Select | before | before — €10.00. after — 10.00€. |
pricing_decimal_places | Select | auto | auto — show decimals only when needed. 0 — whole numbers. 1 — always one decimal place. 2 — always two decimal places. |
pricing_thousands_separator | Select | space | space — 1 000.00. comma — 1,000.00. dot — 1.000,00. none — 1000.00. locale — use the buyer's locale setting. |
Tip: base_price is always required. If you use pricing_tiers, any cart that does not match a tier falls back to base_price.
| Field | Type | Default | Description |
|---|
icon | URL | — | A URL to the carrier logo or custom icon displayed next to the option in checkout. |
estimated_delivery_text | Text | — | Freeform delivery estimate shown to customers, e.g., "Delivered tomorrow" or "2–4 working days". |
estimated_delivery_min_days | Integer | — | Minimum number of days for delivery. Used to generate a structured estimate range. |
estimated_delivery_max_days | Integer | — | Maximum number of days for delivery. Used alongside estimated_delivery_min_days. |
badges | Array | — | Small coloured labels. Each badge has: text (the label), description (tooltip), color (default, discrete, red, green, yellow, blue). |
options | Array | — | Customer-selectable add-ons. Each has: id (machine identifier), description (customer-facing text), type (bool/string/number), fee (optional decimal surcharge), currency (ISO 4217), color (same values as badge), required (boolean — if true, customer cannot deselect). |
delivery_windows | Array | — | Time slots for home delivery. Each has: date (date descriptor, e.g. "today", "tomorrow", or a specific date), time_from (HH:MM 24-hour), time_to (HH:MM 24-hour), fee (optional decimal surcharge), currency (ISO 4217). |
carrier_addons | Array | — | Carrier-specific extras passed through to the carrier API. Each has: id, label, description, enabled (boolean), fee (decimal), currency (ISO 4217), required (boolean — if true, the add-on is always applied), country_codes (text, comma-separated — restrict add-on to these countries), postal_code_prefixes (text, comma-separated — restrict by postcode prefix), cities (text, comma-separated — restrict by city name). |
| Field | Type | Default | Description |
|---|
supports_pickup_points | Boolean | false | Must be enabled for this option to show a pickup point list or map at all. |
pickup_point_types | Array of select | — | Which pickup types to include: service_point (staffed counter), parcel_locker (indoor automated cabinet), outdoor_parcel_locker (outdoor 24/7 locker), store_pickup (your own physical store), home_delivery (standard address delivery). |
pickup_point_listing_mode | Select | combined | combined — mix all enabled types in a single list. separate_by_type — group results by type. |
display_pickup_point_list | Boolean | true | Show pickup points as a scrollable list. |
display_pickup_point_map | Boolean | true | Show pickup points on an interactive map. |
pickup_point_search_by | Select | postal_code | How the pickup search is anchored. postal_code — search by the customer's postcode only. address — search using the full delivery address for a more precise match. |
pickup_point_radius_km | Decimal | — | Limit results to pickup points within this many kilometres. |
pickup_point_limit | Integer | — | Maximum number of pickup locations to return in checkout. Valid range: 1–100. |
pickup_point_exclude_outdoor_lockers | Boolean | false | Explicitly exclude outdoor locker locations even if outdoor_parcel_locker is in pickup_point_types. |
pickup_point_exclude_parcel_lockers | Boolean | false | Explicitly exclude indoor locker locations. |
pickup_point_exclude_service_points | Boolean | false | Explicitly exclude staffed service points. |
| Field | Type | Default | Description |
|---|
parcel_ids | Array of references | — | List of Parcel Preset IDs linked to this shipping option. The linked parcels determine the package dimensions and weight used for carrier rate calculations. |
| Field | Type | Default | Description |
|---|
return_shipment | Boolean | false | Marks this as a returns method. Excluded from standard outbound checkout evaluations. |
return_freight_doc | Boolean | false | Auto-generate a return freight document when this method is used. Only meaningful with return_shipment enabled. |
Warning: Enabling both return_shipment and return_freight_doc at the same time is flagged in the form with a conflict warning. Use return_freight_doc alone when you only want to auto-generate a return document without treating the method as a dedicated returns option. | is_cod | Boolean | false | Cash on delivery — customer pays at the door. Requires a supported checkout provider (Qliro, Walley, Kustom). This field has no toggle in the shipping option form. It is set via the API or preserved when a method is created from a COD template. | | multi_warehouse_mode | Select | — | split_by_origin — each warehouse ships separately, potentially on different days. single_shipment — items from all warehouses are gathered into one combined shipment. |
| Field | Type | Default | Description |
|---|
service_area.mode | Select | all | Controls geographic filtering for this option. all — show this option everywhere. only_matching — show only when the destination matches the filters below. exclude_matching — hide when the destination matches the filters below. |
service_area.country_codes | Text | — | Comma-separated list of ISO 3166-1 alpha-2 country codes to match against. Example: FI,SE,NO. |
service_area.postal_code_prefixes | Text | — | Comma-separated list of postcode prefixes to match against. Example: 001,002,1. |
service_area.cities | Text | — | Comma-separated list of city names to match against. Example: Helsinki,Espoo,Vantaa. |
Tip: Service area filtering is evaluated against the destination address provided in the checkout request. Set mode to all to disable geographic filtering entirely.
| Field | Type | Default | Description |
|---|
translations | Array | — | Per-locale overrides. Each entry has: locale (e.g., fi, sv), name (translated option name), description (translated subtitle). |
| Field | Type | Default | Description |
|---|
rules | Array | — | List of rule objects. Each has conditions (the IF side) and actions (the THEN side). Rules are evaluated in priority order; all matching rules are applied unless stop_after_first_match is enabled. Rule type must be one of the values in the Rule Actions reference. conditions_match can be all (AND logic — every condition must pass) or any (OR logic — at least one condition must pass). |
