POST

Select shipping option

https://api.kustom.co/shipment

This operation reserves the user selected shipping option so that the merchant is able to query and find the data and create a shipment of it.

The shipment reservation should be unique per session_id provided in the request body.

This call happens when the user clicks buy, but before the purchase has gone through. A HTTP 201 response with a location header to this call is interpreted as a confirmation that the selected option is reserved, that the provided recipient data is valid and that the data has been saved successfully.

A HTTP 4xx error code will interrupt the purchase flow and restart the shipping selection process. See failure_reason.

If the purchase is successfully completed, KSS will call POST /shipment/{id}/confirm to confirm the reservation. See the /confirm call.

KSS will occasionally update a created shipment. This can happen because of a failure to finalize the order or for other reasons, which will restart the shipping selection process. See the PUT /shipment call. If the TMS is not able to return a shipment_id in the response, identifying the reserved shipment, then KSS is forced to invoke POST on succeeding updates instead of PUT.

Parameters1 field

Authorizationstringrequiredin header
Authorization token on format Bearer <token>

Request body82 fields

currencystringrequired
ISO 4217 alphabetic currency code
localestring · lc-CCrequired
IETF BCP-47 locale definition
orderobjectoptional
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
- citystringrequired
- 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_namestringrequired
- given_namestringrequired
- phonestringoptional
  E.164 international format
- postal_codestringrequired
  Normalized to country specifications
- regionstringoptional
  Country specific region
- street_addressstringrequired
- street_address2stringoptional
selected_shipping_optionobjectrequired
33 fields in selected_shipping_option
- addons[]array<object>optional
  9 fields in addons
  - dataobjectrequired
    Input from the user.
    2 fields in data
    selectedbooleanoptional
    User selection with the following meaning depending on add-on type:
    
    sms: Indicates whether or not the user wants SMS notifications.
    
    email: Indicates whether or not the user wants email notifications.
    
    floor-number: Should be ignored.
    
    apartment-number: Should be ignored.
    
    entry-code: Should be ignored.
    
    locker-code: Should be ignored.
    
    additional-instructions: Should be ignored.
    
    contactless-delivery: Indicates whether or not the user wants a contactless delivery.
    
    leave-outside-door: Indicates whether or not the user wants the package to be left by their door if they are not home when it arrives.
    
    evening-delivery: Indicates whether or not the user wants an evening delivery.
    
    daytime-delivery: Indicates whether or not the user wants a daytime delivery.
    
    expedited-packing: Indicates whether or not the user wants expedited packing.
    
    sustainable-packaging: Indicates whether or not the user wants sustainable packaging.
    
    carbon-compensated: Indicates whether or not the user wants the shipment to be carbon compensated to the extent that is priced.
    
    indoor-home-delivery: Indicates whether or not the user wants an indoor delivery.
    
    assembly-at-pickup: Indicates whether or not the user wants the goods to be assembled at the pickup location.
    
    package-removal: Indicates whether or not the user wants the package to be removed by the merchant.
    
    textstringoptional
    User input with the following meaning depending on add-on type:
    
    sms: Contains the phone number (non-empty if selected is true).
    
    email: Contains the email address (non-empty if selected is true).
    
    floor-number: Contains the input given by the user (can be empty).
    
    apartment-number: Contains the input given by the user (can be empty).
    
    entry-code: Contains the input given by the user (can be empty).
    
    locker-code: Contains the input given by the user (can be empty).
    
    additional-instructions: Contains the input given by the user (can be empty).
    
    contactless-delivery: Should be ignored.
    
    leave-outside-door: Should be ignored.
    
    evening-delivery: Should be ignored.
    
    daytime-delivery: Should be ignored.
    
    expedited-packing: Should be ignored.
    
    sustainable-packaging: Should be ignored.
    
    carbon-compensated: Should be ignored.
    
    indoor-home-delivery: Should be ignored.
    
    assembly-at-pickup: Should be ignored.
    
    package-removal: Should be ignored.
  - idstringrequired
    The id value from the POST /shippingoptions response.
  - max_lengthintegeroptional
    The max_length value from the POST /shippingoptions response.
  - preselectedbooleanoptional
    The preselected value from the POST /shippingoptions response.
  - priceintegeroptional
    The price value from the POST /shippingoptions response.
  - requiredbooleanoptional
    The required value from the POST /shippingoptions response.
  - typestringrequired
    The type value from the POST /shippingoptions response. Type is one of:
    sms
    email
    floor-number
    apartment-number
    entry-code
    locker-code
    additional-instructions
    contactless-delivery
    leave-outside-door
    evening-delivery
    daytime-delivery
    expedited-packing
    +5 more
- carrierstringoptional
  The carrier for this option
- classstringoptional
  The shipping class for this option
- idstringrequired
  Optional TMS provided identifier
- locationobjectoptional
  12 fields in location
  - 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
  - coordinatesobjectoptional
    Geographical position in decimal degrees
    2 fields in coordinates
    latnumberrequired
    Latitude in decimal degrees
    lngnumberrequired
    Longitude in decimal degrees
  - idstringoptional
    Optional TMS provided identifier
  - namestringoptional
    Name of location
- priceintegeroptional
  Total price for this option in cents, including extras and tax
- tax_rateintegeroptional
  Tax rate of shipping option.
- timeslotobjectoptional
  3 fields in timeslot
  - endstring · date-timerequired
    End of timeslot in ISO 8601 format
  - idstringoptional
    Optional TMS provided identifier
  - startstring · date-timerequired
    Start of timeslot in ISO 8601 format
- typestringoptional
  The type of shipping option
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

Response12 fields

Shipment reservation created and saved successfully

additional_infostringoptional
Any additional information that should be passed to a merchant from TMS can be provided here. Limit is 256 characters.
selected_shipping_optionobjectrequired
5 fields in selected_shipping_option
- 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
- carrier_productobjectoptional
  3 fields in carrier_product
  - addon_identifiers[]array<string>optional
    Product addon identifiers
  - identifierstringoptional
    Carrier identifier/product code
  - namestringoptional
    Carrier product name
shipment_idstringrequired
The id of the (reserved) shipment
shipments[]array<object>optional
3 fields in shipments
- carrierstringoptional
  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
- tracking_idstringoptional
  Carrier-specific tracking id.
- tracking_urlstringoptional
  Carrier-specific URL to a web page where the consumer can see and make changes to their delivery.

201

Response12 fields

Shipment reservation created and saved successfully

additional_infostringoptional
Any additional information that should be passed to a merchant from TMS can be provided here. Limit is 256 characters.
selected_shipping_optionobjectrequired
5 fields in selected_shipping_option
- 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
- carrier_productobjectoptional
  3 fields in carrier_product
  - addon_identifiers[]array<string>optional
    Product addon identifiers
  - identifierstringoptional
    Carrier identifier/product code
  - namestringoptional
    Carrier product name
shipment_idstringrequired
The id of the (reserved) shipment
shipments[]array<object>optional
3 fields in shipments
- carrierstringoptional
  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
- tracking_idstringoptional
  Carrier-specific tracking id.
- tracking_urlstringoptional
  Carrier-specific URL to a web page where the consumer can see and make changes to their delivery.

400

Response1 field

The shipment reservation could not be created, for example if the recipient data is invalid or the selected shipping option is no longer available. The field failure_reason should be one of shipping_option_not_available, cutoff_time_expired or shipping_address_invalid, or if neither is applicable, a text describing the failure reason to simplify debugging.

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/shipment

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

{
  "currency": "SEK",
  "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": {
    "addons": [
      {
        "data": {
          "selected": false,
          "text": "<string>"
        },
        "id": "sms-pickup-point-3",
        "max_length": 4,
        "preselected": false,
        "price": 400,
        "required": false,
        "type": "sms"
      }
    ],
    "carrier": "dhl",
    "class": "express",
    "id": "option-1234",
    "location": {
      "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
      },
      "id": "location-1234",
      "name": "ICA Supermarket"
    },
    "price": 2500,
    "tax_rate": 2500,
    "timeslot": {
      "end": "<date-time>",
      "id": "timeslot-1234",
      "start": "<date-time>"
    },
    "type": "delivery-address"
  },
  "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"
}

106 lines

Response 200· Shipment reservation created and saved successfully

{
  "additional_info": "<string>",
  "selected_shipping_option": {
    "carrier": "postnord",
    "carrier_product": {
      "addon_identifiers": [
        "1"
      ],
      "identifier": "19",
      "name": "MyPack"
    }
  },
  "shipment_id": "c2059e35-58b1-4482-ad55-5e7ef541eae4",
  "shipments": [
    {
      "carrier": "postnord",
      "tracking_id": "<string>",
      "tracking_url": "<string>"
    }
  ]
}

21 lines

Response 201· Shipment reservation created and saved successfully

{
  "additional_info": "<string>",
  "selected_shipping_option": {
    "carrier": "postnord",
    "carrier_product": {
      "addon_identifiers": [
        "1"
      ],
      "identifier": "19",
      "name": "MyPack"
    }
  },
  "shipment_id": "c2059e35-58b1-4482-ad55-5e7ef541eae4",
  "shipments": [
    {
      "carrier": "postnord",
      "tracking_id": "<string>",
      "tracking_url": "<string>"
    }
  ]
}

21 lines

Response 400· The shipment reservation could not be created, for example if the recipient dat…

{
  "failure_reason": "shipping_option_not_available"
}

3 lines

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