POST

List shipping options

https://api.kustom.co/shippingoptions

Gets shipping options for the given customer data, address and order lines.

It’s always important to display proper expected delivery date and time, to create a smoooth customer experience. Below you can find a table with examples of how customer will see delivery date and time that is provided in the delivery_time field of shipping option. Representation can vary in case provided date points to the same date or a period, in case the date is today, tomorrow or any date in the future. Dates in the past are ignored.

Provided values	UI presentation	Examples
delivery_time.interval.earliest	Delivered after `delivery_time.interval.earliest` business days	Delivered after 3 business days
delivery_time.interval.latest	Delivered within `delivery_time.interval.latest` business days	Delivered within 3 business days
delivery_time.interval.earliest delivery_time.interval.latest	Delivered in `delivery_time.interval.earliest`-`delivery_time.interval.latest` business days	Delivered in 2-7 business days
delivery_time.interval.earliest delivery_time.cutoff	Delivered after `delivery_time.interval.earliest` business days, if ordered before `delivery_time.cutoff`	Delivered after 7 business days, if ordered before 14:00
delivery_time.interval.latest delivery_time.cutoff	Delivered within `delivery_time.interval.latest` business days, if ordered before `delivery_time.cutoff`	Delivered within 7 business days, if ordered before 14:00
delivery_time.interval.earliest delivery_time.interval.latest delivery_time.cutoff	Delivered in `delivery_time.interval.earliest`-`delivery_time.interval.latest` business days, if ordered before `delivery_time.cutoff`	Delivered in 1-5 business days, if ordered before 11:30
delivery_time.interval.earliest delivery_time.time_of_day.earliest delivery_time.time_of_day.latest	Delivered after `delivery_time.interval.earliest` business days between ca. `delivery_time.time_of_day.earliest` and `delivery_time.time_of_day.latest`	Delivered after 3 business days between ca 17:00 and 18:00
delivery_time.interval.latest delivery_time.time_of_day.earliest delivery_time.time_of_day.latest	Delivered within `delivery_time.interval.latest` business days between ca. `delivery_time.time_of_day.earliest` and `delivery_time.time_of_day.latest`	Delivered within 5 business days between ca 8:00 and 17:00
delivery_time.interval.earliest delivery_time.interval.latest delivery_time.time_of_day.earliest delivery_time.time_of_day.latest	Delivered in `delivery_time.interval.earliest`-`delivery_time.interval.latest` business days between ca. `delivery_time.time_of_day.earliest` and `delivery_time.time_of_day.latest`	Delivered in 1-2 business days between ca 9:00 and 12:00
delivery_time.interval.earliest delivery_time.cutoff delivery_time.time_of_day.earliest delivery_time.time_of_day.latest	Delivered after `delivery_time.interval.earliest` business days between ca. `delivery_time.time_of_day.earliest` and `delivery_time.time_of_day.latest`, if ordered before `delivery_time.cutoff`	Delivered after 4 business days between ca. 16:00 and 18:00, if ordered before 11:30
delivery_time.interval.latest delivery_time.cutoff delivery_time.time_of_day.earliest delivery_time.time_of_day.latest	Delivered within `delivery_time.interval.latest` business days between ca. `delivery_time.time_of_day.earliest` and `delivery_time.time_of_day.latest`, if ordered before `delivery_time.cutoff`	Delivered within 3 business days between ca 10:00 and 17:00, if ordered before 11:30
delivery_time.interval.earliest delivery_time.interval.latest delivery_time.cutoff delivery_time.time_of_day.earliest delivery_time.time_of_day.latest	Delivered in `delivery_time.interval.earliest`-`delivery_time.interval.latest` business days between ca. `delivery_time.time_of_day.earliest` and `delivery_time.time_of_day.latest`, if ordered before `delivery_time.cutoff`	Delivered in 1-5 business days between ca 15:00 and 17:00, if ordered before 11:30
delivery_time.earliest	Delivered `delivery_time.earliest` at the earliest	Delivered tomorrow at the earliest Delivered Thursday March 5 at the earliest
delivery_time.latest	Delivered no later than `delivery_time.latest`	Delivered today Delivered no later than tomorrow Delivered no later than Thursday, March 4
delivery_time.earliest delivery_time.latest	Delivered between `delivery_time.earliest` and `delivery_time.latest`	Delivered today Delivered no later than tomorrow Delivered tomorrow Delivered between Wednesday March 4 and Friday March 6 Delivered Monday April 6 Delivered between Monday April 6 and Friday May 24
delivery_time.earliest delivery_time.cutoff	Delivered `delivery_time.earliest` at the earliest, if ordered before `delivery_time.cutoff`	Delivered Saturday, July 25 at the earliest, if ordered before 15:00 Delivered tomorrow, if ordered before 14:00
delivery_time.latest delivery_time.cutoff	Delivered no later than `delivery_time.latest`, if ordered before `delivery_time.cutoff`	Delivered no later than Sunday, June 4, if ordered before 20:00 Delivered tomorrow, if ordered before 14:00
delivery_time.earliest delivery_time.latest delivery_time.cutoff	Delivered between `delivery_time.earliest` and `delivery_time.latest`, if ordered before `delivery_time.cutoff`	Delivered between Monday March 4 and Wednesday March 6, if ordered before 12:00 Delivered tomorrow, if ordered before 14:00
delivery_time.earliest delivery_time.time_of_day.earliest delivery_time.time_of_day.latest	Delivered `delivery_time.earliest` at the earliest, from `delivery_time.time_of_day.earliest` to `delivery_time.time_of_day.latest`	Delivered Saturday March 13 at the earliest, from 15:00 to 17:00
delivery_time.latest delivery_time.time_of_day.earliest delivery_time.time_of_day.latest	Delivered no later than `delivery_time.latest`, from `delivery_time.time_of_day.earliest` to `delivery_time.time_of_day.latest`	Delivered no later than Sunday November 9, from 9:00 to 15:00
delivery_time.earliest delivery_time.latest delivery_time.time_of_day.earliest delivery_time.time_of_day.latest	Delivered between `delivery_time.earliest` and `delivery_time.latest`, from `delivery_time.time_of_day.earliest` to `delivery_time.time_of_day.latest`	Delivered between Monday March 9 and Friday March 13, from 10:00 to 18:00
delivery_time.earliest delivery_time.cutoff delivery_time.time_of_day.earliest delivery_time.time_of_day.latest	Delivered `delivery_time.earliest` at the earliest, from `delivery_time.time_of_day.earliest` to `delivery_time.time_of_day.latest`, if ordered before `delivery_time.cutoff`	Delivered tomorrow at the earliest, from 15:00 to 18:00, if ordered before 21:00
delivery_time.latest delivery_time.cutoff delivery_time.time_of_day.earliest delivery_time.time_of_day.latest	Delivered no later than `delivery_time.latest`, from `delivery_time.time_of_day.earliest` to `delivery_time.time_of_day.latest`, if ordered before `delivery_time.cutoff`	Delivered no later than tmorrow, from 21:00 to 23:00, if ordered before 15:00
delivery_time.earliest delivery_time.latest delivery_time.cutoff delivery_time.time_of_day.earliest delivery_time.time_of_day.latest	Delivered between `delivery_time.earliest` and `delivery_time.latest`, from `delivery_time.time_of_day.earliest` to `delivery_time.time_of_day.latest`, if ordered before `delivery_time.cutoff`	Delivered between Monday March 9 and Friday March 13, from 15:00 to 17:00, if ordered before 11:30

Parameters1 field

Authorizationstringrequiredin header
Authorization token on format Bearer <token>

Request body50 fields

currencystringrequired
ISO 4217 alphabetic currency code.
geoblockingbooleanoptional
A flag that indicates if the requested shipping options are for geoblocking flow.

Example: abc.se has consumers in e.g. Norway. According to Konsumentverket, these consumers should be given “the same opportunity to buy as a Swedish consumer”.

User Flows:
1. A Norwegian consumer enters abc.se
2. The consumer selects Norway as billing country and fills in his/her address
3. Shipping module will display an information box saying “We do not deliver to the country specified in your billing address. Please select an alternative shipping option below.”
4. The consumer chooses the delivery country (only if more than one is available).
  1. The consumer either fills in an address and gets a full set of shipping options OR
  2. The consumer chooses not to fill in an address and gets presented with only pickup-merchant-store shipping options with all the Swedish stores as locations.
localestring · lc-CCrequired
IETF BCP-47 locale definition.
orderobjectrequired
Order definition
21 fields in order
- tags[]array<string>optional
  TMS defined order or order line attributes. The tags are passed in by the merchant during order creation and passed along as is.
  
  The TMS and Merchant use tags to direct custom business logic between themselves: (Note that these tags are examples and NOT required or related to KSS in any way)
  - Pricing
  - Option Configuration
  - Customer Metadata
  Different tags are allowed on order and order line level. For example, a merchant can provide order line detail of signifcance to the TMS, i.e. ["age_restricted","bulky"]
- idstringoptional
  Kustom order id, will be known at time of purchase and only provided in the /shipment call. No assumption should be made about the format.
- lines[]array<object>required
  15 fields in lines
  - attributesobjectoptional
    6 fields in attributes
    tags[]array<string>optional
    TMS defined order or order line attributes. The tags are passed in by the merchant during order creation and passed along as is.
    
    The TMS and Merchant use tags to direct custom business logic between themselves: (Note that these tags are examples and NOT required or related to KSS in any way)
    
    Pricing
    
    `promo17`
    
    Option Configuration
    
    `next_day_only`
    
    `sort_by_cost_asc`
    
    `limit_8`
    
    Customer Metadata
    
    `member`
    
    `platinum`
    
    Different tags are allowed on order and order line level. For example, a merchant can provide order line detail of signifcance to the TMS, i.e. ["age_restricted","bulky"]
    dimensionsobjectoptional
    Dimensions of this item
    3 fields in dimensions
    heightintegeroptional
    height in mm
    lengthintegeroptional
    length in mm
    widthintegeroptional
    width in mm
    weightintegeroptional
    Weight of this item in grams
  - quantityintegerrequired
  - referencestringoptional
    Merchant provided item reference
  - tax_rateintegerrequired
    Tax rate of shipping option in percent. Non-negative, two implicit decimals. I.e 2500 = 25.00%.
  - total_discount_amountintegeroptional
    Total discount amount in cents
  - total_price_including_taxintegerrequired
    Total price of items, including tax, given in cents
  - total_tax_amountintegerrequired
    Total tax amount in cents
  - typestringoptional
    Order line type.
    physical
    discount
    shipping_fee
    sales_tax
    digital
    gift_card
    store_credit
    surcharge
  - unit_priceintegerrequired
    Unit price in cents
- total_amountintegerrequired
  Total order amount including tax in cents.
- total_taxintegerrequired
  Total tax of the order amount in cents.
- total_weightintegeroptional
  Total weight in grams
recipientobjectrequired
Information about the recipient
13 fields in recipient
- care_ofstringoptional
- citystringoptional
- company_namestringoptional
  Applicable only if recipient is a company
- countrystringrequired
  2 character ISO 3166 country format
- customer_typestringoptional
  B2C or B2B customer type. Note: does only indicate the type of customer, not if the address is residential or business.
  - person
  - organization
- emailstringoptional
- family_namestringoptional
- given_namestringoptional
- phonestringoptional
  E.164 international format
- postal_codestringoptional
  Normalized to country specifications
- regionstringoptional
  Country specific region
- street_addressstringoptional
- street_address2stringoptional
selected_shipping_option_idstringoptional
Informs what selected shipping option is currently selected by an enduser. When this information is provided it means that the API caller wants to refine the locations for the selected shipping option. The API endpoint should restrict its response to the selected shipping option only and base the refinement on the recipient data. The recipient data is temporary and should not replace any state persistent (if any) based on previous recipient data received in prior shippingoptions calls.
senderobjectoptional
Information about the sender. Should indicate from where the goods are dispatched. This object is optional and can be empty.
8 fields in sender
- addressobjectoptional
  6 fields in address
  - citystringrequired
  - countrystringrequired
    2 character ISO 3166 country format
  - postal_codestringrequired
    Normalized to country specifications
  - regionstringoptional
    Country specific region
  - street_addressstringrequired
  - street_address2stringoptional
- sender_idstringoptional
  Optional merchant provided sender identifier. Can be used to identify different warehouses within the same country or different dispatch routes that can affect delivery time.
session_idstringrequired
Unique Kustom shipping session id.

200

Response121 fields

shipping_options[]array<object>optional
120 fields in shipping_options
- addons[]array<object>optional
  7 fields in addons
  - idstringoptional
    Pass-through custom ID field set by the API provider. Can be used by the API provider to match add-ons in the POST /shipment request with add-ons from the POST /shippingoptions response.
  - max_lengthintegeroptional
    Applies to text input add-ons. Maximum length of the text. If unset, no limit is applied.
  - preselectedbooleanoptional
    If set to true, the add-on is selected by default (can be unselected by the user). Only applies to add-ons that are explicitly selectable (e.g., checkboxes and addresses, but not text inputs).
  - priceintegeroptional
    Additional cost in cents, including tax, that will be added to the option’s price if the add-on is selected.
  - requiredbooleanoptional
    If true, the add-on is marked as mandatory and the user cannot finalize the purchase without selecting it or otherwise filling the required information.
  - typestringrequired
    Each add-on type must appear at most once per shipping option.
    
    Type is one of:
    
    sms: Displays a checkbox and an input field for a phone number, for SMS notifications on delivery status updates.
    
    email: Displays a checkbox and an input field for an email address, for email notifications on delivery status updates.
    
    floor-number: Displays an input field where the consumer can provide the exact floor they live on within a building.
    
    apartment-number: Displays an input field where the consumer can provide their exact apartment number for the courier.
    
    entry-code: Displays an input field where the consumer can provide an entry code, e.g. for the building front door.
    
    locker-code: Displays an input field where the consumer can provide a locker code, e.g. for the post box.
    
    additional-instructions: Displays an input field where the consumer can provide additional delivery information for the courier.
    
    contactless-delivery: Displays a checkbox for selecting a contactless delivery. Only available in the Nordics and Germany.
    
    leave-outside-door: Displays a checkbox to allow the package to be left by the shopper’s door if they are not home when it arrives. Only available in the Nordics and Germany.
    
    evening-delivery: Displays a checkbox for selecting an evening delivery, between 17:00 and 22:00 on any of the delivery days.
    
    daytime-delivery: Displays a checkbox for selecting a daytime delivery, between 08:00 and 17:00 on any of the delivery days.
    
    expedited-packing: Displays a checkbox for selecting expedited packing. This represents a commitment from the merchant to prioritize this order within any warehouse handling or dispatch processes.
    
    reusable-packaging: Displays a checkbox for selecting reusable packaging. This represents a commitment from the merchant to send this order using reusable packaging.
    
    sustainable-packaging: Displays a checkbox for selecting sustainable packaging. This represents a commitment from the merchant to ensure the delivery uses easily recyclable or reusable packaging.
    
    carbon-compensated: Displays a checkbox for the user to make a carbon offsetting donation. Contact your account manager if you would like to explore this area further in partnership with us.
    
    indoor-home-delivery: Displays a checkbox for selecting an indoor delivery, e.g. for large homewares or white goods.
    
    assembly-at-pickup: Displays a checkbox for selecting assembly of the goods, e.g. for sports equipment like bikes or home and garden items.
    
    package-removal: Displays a checkbox to allow the package to be removed by the merchant.
  - urlstringoptional
    Displays a ‘Learn more’ link to a web page with more information about the addon.
- areaobjectoptional
  DRAFT - Geographically enclosed delivery area. WIP: Specifications might change.
  5 fields in area
  - boundary[]array<object>required
    Polygon definition of enclosed area using decimal degree geographical coordinates
    2 fields in boundary
    latnumberrequired
    Latitude in decimal degrees
    lngnumberrequired
    Longitude in decimal degrees
  - priceintegeroptional
    Price in cents including tax for this area, if different from base price. Tax rate from base price.
  - typestringrequired
    The type of area enclosed by the boundaries
    archipelago
    urban
    suburban
    rural
- carrierstringrequired
  Transportation carrier company used.
  - merchant can be used for merchant self-hosted delivery methods (ex. instore pickup).
  - generic-postal can be used to indicate a generic postal network.
  - Additional carriers can be supported on request.
  Value should be one of:
  - acs-courier
  - airmee
  - an-post
  - asendia
  - australia-post
  - austrian-post
  - bartolini
  - best
  - bpost
  - bring
  - bring-green
  - budbee
  - +94 more
- classstringoptional
  Description:
  - standard: Normal delivery time.
  - economy: Slow delivery.
  - express: Fast delivery.
  - courier: Fastest delivery time, like food delivery.
  Value should be one of:
  - standard
  - economy
  - express
  - courier
- delivery_timeobjectoptional
  Defines earliest and latest estimated delivery dates and/or times and the cutoff time for these delivery times to be met. Is used to indicate estimated delivery time to the user. Timezone should be given if time is supplied, otherwise zulu is assumed.
  
  NOTE: The interval object always overrides the explicit earliest and latest delivery dates (which means these will be ignored if an interval is set).
  10 fields in delivery_time
  - cutoffstring · date-timeoptional
    Delivery times are only valid if order is placed before this time, in ISO 8601 format.
  - earlieststring · date-timeoptional
    Earliest possible delivery date, in ISO 8601 format.
  - intervalobjectoptional
    Defines offsets for earliest and latest estimated delivery dates, in business days. Timezone offset should be given in terms of UTC offset in seconds (see utc_offset_in_seconds), otherwise 0 is assumed.
    3 fields in interval
    earlieststringoptional
    Date offset (in business days) that will be added to current local time in UTC and be presented as a delivery_time earliest date.
    lateststringoptional
    Date offset (in business days) that will be added to current local time in UTC and be presented as a delivery_time latest date.
    utc_offset_in_secondsstringoptional
    The UTC offset (in seconds) that will be used when formatting the evaluated date/time.
  - lateststring · date-timeoptional
    Parcel will be delivered at latest this date, in ISO 8601 format.
  - time_of_dayobjectoptional
    Defines earliest and latest estimated delivery times of day.
    2 fields in time_of_day
    earlieststring · date-timeoptional
    Defines earliest estimated delivery time in ISO 8601 format. The date part will be ignored.
    lateststring · date-timeoptional
    Defines latest estimated delivery time in ISO 8601 format. The date part will be ignored.
- features[]array<object>optional
  4 fields in features
  - classstringoptional
    Determines if the feature is an simple information box or a badge. Badges are eye-catching and colourful, highlighting a particular feature of the shipping option to draw the shopper’s attention.
    info
    badge
    call_to_action
  - merchant_info_textstringoptional
    Text to be displayed in the info-box. Only applicable when type is merchant_info_text.
  - typestringrequired
    This string will determine the feature applied. Info-boxes:
    
    distributor-will-contact: Displays an info-box to say the distributor will contact the shopper afterwards.
    
    package-removal: Displays an info-box to say the carrier will remove the packaging and dispose of it on behalf of the shopper.
    
    room-delivery: Displays an info-box to say the order will be delivered and carried into the room of the shopper's choice.
    
    delivery-time-extra-info: Displays an info-box to say the stated number of days refers to the shipping time from the merchant to the consumer.
    
    multiple-deliveries-info: Displays an info-box to say that the order will be split into multiple deliveries.
    
    merchant-info-text: Displays an info-box with the text provided in merchant_info_text
    
    Badges:
    
    afternoon: Displays a badge highlighting that the option is an afternoon delivery option.
    
    carbon-compensated: Displays a badge highlighting that the option will be carbon compensated.
    
    eco-friendly: Displays a badge highlighting that the option is environmentally friendly.
    
    evening: Displays a badge highlighting that the option is an evening delivery option.
    
    express: Displays a badge highlighting that the option is an express option.
    
    fossil-free: Displays a badge highlighting that the shipping option is fossil free.
    
    in-door-home-delivery: Displays a badge highlighting that the shipment will be delivered indoors.
    
    morning: Displays a badge highlighting that the option is a moning delivery option.
    
    multiple-deliveries: Displays a badge highlighting that the shipment will be split into multiple deliveries.
    
    outdoor-home-delivery: Displays a badge highlighting that the shipment will be delivered outdoors.
    
    recommended: Displays a badge highlighting that the option recommended by the merchant.
    
    traceable: Displays a badge highlighting that the shipping option is traceable.
    
    Call to actions:
    
    learn-more: Displays a 'Learn more' link to a URL with more information about the feature.
    
    size-guide: Displays a 'Size Guide' icon that links to URL with a size guide.
  - urlstringoptional
    Displays a link to a web page with information about the feature. Only applicable when class is call_to_action.
- free_aboveintegeroptional
  The total amount threshold at which the shipping option price becomes free, i.e. 0.00. In cents, i.e. 10000 = 100.00.
- idstringrequired
  Aggregator provided identifier. Must be unique.
- locations[]array<object>optional
  Location definitions of pickup points/boxes, store locations, etc.
  74 fields in locations
  - addressobjectrequired
    6 fields in address
    citystringrequired
    countrystringrequired
    2 character ISO 3166 country format
    postal_codestringrequired
    Normalized to country specifications
    regionstringoptional
    Country specific region
    street_addressstringrequired
    street_address2stringoptional
  - coordinatesobjectoptional
    Geographical position in decimal degrees
    2 fields in coordinates
    latnumberrequired
    Latitude in decimal degrees
    lngnumberrequired
    Longitude in decimal degrees
  - delivery_timeobjectoptional
    Defines earliest and latest estimated delivery dates and/or times and the cutoff time for these delivery times to be met. Is used to indicate estimated delivery time to the user. Timezone should be given if time is supplied, otherwise zulu is assumed.
    
    NOTE: The interval object always overrides the explicit earliest and latest delivery dates (which means these will be ignored if an interval is set).
    10 fields in delivery_time
    cutoffstring · date-timeoptional
    Delivery times are only valid if order is placed before this time, in ISO 8601 format.
    earlieststring · date-timeoptional
    Earliest possible delivery date, in ISO 8601 format.
    intervalobjectoptional
    Defines offsets for earliest and latest estimated delivery dates, in business days. Timezone offset should be given in terms of UTC offset in seconds (see utc_offset_in_seconds), otherwise 0 is assumed.
    3 fields in interval
    earlieststringoptional
    Date offset (in business days) that will be added to current local time in UTC and be presented as a delivery_time earliest date.
    lateststringoptional
    Date offset (in business days) that will be added to current local time in UTC and be presented as a delivery_time latest date.
    utc_offset_in_secondsstringoptional
    The UTC offset (in seconds) that will be used when formatting the evaluated date/time.
    lateststring · date-timeoptional
    Parcel will be delivered at latest this date, in ISO 8601 format.
    time_of_dayobjectoptional
    Defines earliest and latest estimated delivery times of day.
    2 fields in time_of_day
    earlieststring · date-timeoptional
    Defines earliest estimated delivery time in ISO 8601 format. The date part will be ignored.
    lateststring · date-timeoptional
    Defines latest estimated delivery time in ISO 8601 format. The date part will be ignored.
  - idstringoptional
    Optional TMS provided identifier, will be passed back if provided.
  - namestringrequired
    User friendly name of location (pickup point, store name, etc).
  - operational_hoursobjectoptional
    Opening and closing times for a location (24 hs Format. e.g. ‘09:00’, ‘18:00’). If operational hours are unknown, do not provide this object. Otherwise, provide hours or an open/closed status for each day, either using default hours or providing overrides for each day of the week.
    49 fields in operational_hours
    default[]array<object>optional
    Opening and closing hours (24 hs Format. e.g. ‘09:00’, ‘18:00’) OR an open/closed status for each day of the week
    4 fields in default
    always_openbooleanoptional
    Open all day
    closestringoptional
    24 hs Format (e.g. 18:00)
    closedbooleanoptional
    Closed all day
    openstringoptional
    24 hs Format (e.g. 09:00)
    overridesobjectoptional
    43 fields in overrides
    date[]array<object>optional
    6 fields in date
    datestring · dateoptional
    hoursobjectoptional
    Opening and closing times for (part of) a given day (24 hs Format. e.g. ‘09:00’, ‘18:00’). Assumes local timezone.
    4 fields in hours
    always_openbooleanoptional
    Open all day
    closestringoptional
    24 hs Format (e.g. 18:00)
    closedbooleanoptional
    Closed all day
    openstringoptional
    24 hs Format (e.g. 09:00)
    weekdayobjectoptional
    35 fields in weekday
    fri[]array<object>optional
    4 fields in fri
    always_openbooleanoptional
    Open all day
    closestringoptional
    24 hs Format (e.g. 18:00)
    closedbooleanoptional
    Closed all day
    openstringoptional
    24 hs Format (e.g. 09:00)
    mon[]array<object>optional
    4 fields in mon
    always_openbooleanoptional
    Open all day
    closestringoptional
    24 hs Format (e.g. 18:00)
    closedbooleanoptional
    Closed all day
    openstringoptional
    24 hs Format (e.g. 09:00)
    sat[]array<object>optional
    4 fields in sat
    always_openbooleanoptional
    Open all day
    closestringoptional
    24 hs Format (e.g. 18:00)
    closedbooleanoptional
    Closed all day
    openstringoptional
    24 hs Format (e.g. 09:00)
    sun[]array<object>optional
    4 fields in sun
    always_openbooleanoptional
    Open all day
    closestringoptional
    24 hs Format (e.g. 18:00)
    closedbooleanoptional
    Closed all day
    openstringoptional
    24 hs Format (e.g. 09:00)
    thu[]array<object>optional
    4 fields in thu
    always_openbooleanoptional
    Open all day
    closestringoptional
    24 hs Format (e.g. 18:00)
    closedbooleanoptional
    Closed all day
    openstringoptional
    24 hs Format (e.g. 09:00)
    tue[]array<object>optional
    4 fields in tue
    always_openbooleanoptional
    Open all day
    closestringoptional
    24 hs Format (e.g. 18:00)
    closedbooleanoptional
    Closed all day
    openstringoptional
    24 hs Format (e.g. 09:00)
    wed[]array<object>optional
    4 fields in wed
    always_openbooleanoptional
    Open all day
    closestringoptional
    24 hs Format (e.g. 18:00)
    closedbooleanoptional
    Closed all day
    openstringoptional
    24 hs Format (e.g. 09:00)
  - priceintegeroptional
    Price in cents including tax for this location, if different from base price. Tax rate from base price.
- namestringoptional
  Carrier product name. Will only be used as a fallback in case Kustom does not have a proper copy string for the shipping option.
- previewbooleanoptional
  Should be set to true if this option was included as a result of partial address data and that it might be changed or removed when full address data is available.
- priceintegerrequired
  Price of shipping option in cents including tax. I.e. 4000 = 40.00.
- tax_rateintegerrequired
  Tax rate of shipping option in percent. Non-negative, two implicit decimals. I.e 2500 = 25.00%. The amount of tax will be calculated as price - (price * 10000 / (10000 + tax_rate)).
- timeslots[]array<object>optional
  Timeslot definition, only applicable to delivery methods with timeslots.
  5 fields in timeslots
  - cutoffstring · date-timeoptional
    Timeslot only valid if order is placed before this time
  - endstring · date-timerequired
    End time of slot in ISO 8601 format
  - idstringoptional
    Optional TMS provided identifier, will be passed back if provided
  - priceintegeroptional
    Price in cents including tax for this slot, if different from base price. Tax rate from base price.
  - startstring · date-timerequired
    Start time of slot in ISO 8601 format
- typestringrequired
  - boat-delivery: Delivery by boat.
  - click-collect: Order goods online for reservation and pick up at a merchant store.
  - delivery-address: To address/door delivery, final selected option will contain an address and potential timeslot.
  - generic-pickup: Delivery to a pickup point when location is unknown.
  - generic-shipping: Shipping option when the carrier decides shipping method.
  - office-delivery: Delivery to an office address. For eg. to an office reception.
  - pallet-delivery: Home delivery of big/heavy goods by truck and on a pallet.
  - crane-delivery: Delivery by crane for very large goods, such as pools and jacuzzis.
  - pickup-box: Delivery to a pickup locker/box. Final selected option will contain a location.
  - pickup-merchant-store: Delivery to a merchant store for pickup. Final selected option will contain a location.
  - pickup-point: Delivery to a pickup point. Final selected option will contain a location.
  - pickup-warehouse: Delivery to a merchant warehouse for pick up.
  - postal: Best-effort delivery of a package/letter using the postal network.

400

Response1 field

The /shippingoptions request was malformed. In order to simplify debugging, the field failure_reason should contain a text describing the failure reason.

failure_reasonstringoptional

401

Response0 fields

Invalid or expired token. A new token will be obtained.

No response body — this status returns headers only.

POST https://api.kustom.co/shippingoptions

Request body· application/vdn.klarna.shipping.get_options-v1+json

{
  "currency": "SEK",
  "geoblocking": true,
  "locale": "sv-SE",
  "order": {
    "tags": [
      "member"
    ],
    "id": "<string>",
    "lines": [
      {
        "attributes": {
          "tags": [
            "member"
          ],
          "dimensions": {
            "height": 5000,
            "length": 5000,
            "width": 5000
          },
          "weight": 1000
        },
        "quantity": 2,
        "reference": "sku-1234",
        "tax_rate": 2500,
        "total_discount_amount": 1000,
        "total_price_including_tax": 4000,
        "total_tax_amount": 1250,
        "type": "physical",
        "unit_price": 2500
      }
    ],
    "total_amount": 10000,
    "total_tax": 2500,
    "total_weight": 2000
  },
  "recipient": {
    "care_of": "<string>",
    "city": "Stockholm",
    "company_name": "Kustom AB",
    "country": "SE",
    "customer_type": "person",
    "email": "info@kustom.com",
    "family_name": "Joyce",
    "given_name": "Klara",
    "phone": "+46812012010",
    "postal_code": "111 34",
    "region": "CA",
    "street_address": "Sveavägen 46",
    "street_address2": "<string>"
  },
  "selected_shipping_option_id": "tms-specific-shipping-option-id",
  "sender": {
    "address": {
      "city": "Stockholm",
      "country": "SE",
      "postal_code": "111 34",
      "region": "CA",
      "street_address": "Sveavägen 46",
      "street_address2": "<string>"
    },
    "sender_id": "warehouse-13"
  },
  "session_id": "201cda14-975f-4c4d-9c2f-12f3896b5156"
}

65 lines

Response 200

{
  "shipping_options": [
    {
      "addons": [
        {
          "id": "sms-pickup-point-3",
          "max_length": 4,
          "preselected": false,
          "price": 400,
          "required": false,
          "type": "<string>",
          "url": "https://www.kustom.co"
        }
      ],
      "area": {
        "boundary": [
          {
            "lat": 18.062689527869225,
            "lng": 59.33655850186736
          },
          {
            "lat": 18.063891157507896,
            "lng": 59.336892270502865
          },
          {
            "lat": 18.06284509599209,
            "lng": 59.33791817815379
          },
          {
            "lat": 18.061750754714012,
            "lng": 59.337655548745
          }
        ],
        "price": 5000,
        "type": "archipelago"
      },
      "carrier": "postnord",
      "class": "standard",
      "delivery_time": {
        "cutoff": "2017-07-21T17:32:28Z",
        "earliest": "2017-07-21T17:32:28Z",
        "interval": {
          "earliest": "3",
          "latest": "5",
          "utc_offset_in_seconds": "3600"
        },
        "latest": "2017-07-21T17:32:28Z",
        "time_of_day": {
          "earliest": "2017-07-21T17:32:28Z",
          "latest": "2017-07-21T19:32:28Z"
        }
      },
      "features": [
        {
          "class": "info",
          "merchant_info_text": "<string>",
          "type": "<string>",
          "url": "https://www.kustom.co"
        }
      ],
      "free_above": 10000,
      "id": "option-1234",
      "locations": [
        {
          "address": {
            "city": "Stockholm",
            "country": "SE",
            "postal_code": "111 34",
            "region": "CA",
            "street_address": "Sveavägen 46",
            "street_address2": "<string>"
          },
          "coordinates": {
            "lat": 59.336946,
            "lng": 18.063095
          },
          "delivery_time": {
            "cutoff": "2017-07-21T17:32:28Z",
            "earliest": "2017-07-21T17:32:28Z",
            "interval": {
              "earliest": "3",
              "latest": "5",
              "utc_offset_in_seconds": "3600"
            },
            "latest": "2017-07-21T17:32:28Z",
            "time_of_day": {
              "earliest": "2017-07-21T17:32:28Z",
              "latest": "2017-07-21T19:32:28Z"
            }
          },
          "id": "loc-12345",
          "name": "ICA supermarket",
          "operational_hours": {
            "default": [
              {
                "always_open": false,
                "close": "22:00",
                "closed": false,
                "open": "09:00"
              }
            ],
            "overrides": {
              "date": [
                {
                  "date": "2017-12-24",
                  "hours": {
                    "always_open": false,
                    "close": "22:00",
                    "closed": false,
                    "open": "09:00"
                  }
                }
              ],
              "weekday": {
                "fri": [
                  {
                    "always_open": false,
                    "close": "22:00",
                    "closed": false,
                    "open": "09:00"
                  }
                ],
                "mon": [
                  {
                    "always_open": false,
                    "close": "22:00",
                    "closed": false,
                    "open": "09:00"
                  }
                ],
                "sat": [
                  {
                    "always_open": false,
                    "close": "22:00",
                    "closed": false,
                    "open": "09:00"
                  }
                ],
                "sun": [
                  {
                    "always_open": false,
                    "close": "22:00",
                    "closed": false,
                    "open": "09:00"
                  }
                ],
                "thu": [
                  {
                    "always_open": false,
                    "close": "22:00",
                    "closed": false,
                    "open": "09:00"
                  }
                ],
                "tue": [
                  {
                    "always_open": false,
                    "close": "22:00",
                    "closed": false,
                    "open": "09:00"
                  }
                ],
                "wed": [
                  {
                    "always_open": false,
                    "close": "22:00",
                    "closed": false,
                    "open": "09:00"
                  }
                ]
              }
            }
          },
          "price": 0
        }
      ],
      "name": "FedEx Priority",
      "preview": false,
      "price": 4000,
      "tax_rate": 2500,
      "timeslots": [
        {
          "cutoff": "2017-07-21T17:32:28Z",
          "end": "2017-07-21T17:32:28Z",
          "id": "slot-12345",
          "price": 0,
          "start": "2017-07-21T17:32:28Z"
        }
      ],
      "type": "pickup-point"
    }
  ]
}

193 lines

Response 400· The /shippingoptions request was malformed.

{
  "failure_reason": "Field 'xxx.yyy.example' must not be empty."
}

3 lines

This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.