# Update the shipping option

> `PUT https://api.kustom.co/shipment/{shipment_id}`

This operation updates the previously created shipment reservation (`POST -> /shipment`).

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. This request takes place if relevant data were updated or if the user was denied a preceding purchase after /shipment call took place. The user then has the potential to change his previous selections and retry the purchase.

A HTTP 200 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 updated successfully.

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

## Parameters

- `shipment_id` (string, path, required) — Unique shipment ID
- `Authorization` (string, header, required) — Authorization token on format `Bearer <token>`.

## Request body

`application/vdn.klarna.shipping.select_option-v1+json`

- `currency` (string, required) — ISO 4217 alphabetic currency code
- `locale` (string, required) — IETF BCP-47 locale definition
- `order` (object) — Order definition
  - `tags[]` (array<string>) — 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"]`
  - `id` (string) — 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)
    - `attributes` (object)
      - `tags[]` (array<string>) — 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"]`
      - `dimensions` (object) — Dimensions of this item
        - `height` (integer) — height in mm
        - `length` (integer) — length in mm
        - `width` (integer) — width in mm
      - `weight` (integer) — Weight of this item in grams
    - `quantity` (integer, required)
    - `reference` (string) — Merchant provided item reference
    - `tax_rate` (integer, required) — Tax rate of shipping option in percent. Non-negative, two implicit decimals. I.e 2500 = 25.00%.
    - `total_discount_amount` (integer) — Total discount amount in cents
    - `total_price_including_tax` (integer, required) — Total price of items, including tax, given in cents
    - `total_tax_amount` (integer, required) — Total tax amount in cents
    - `type` (string) — Order line type. Enum: `physical`, `discount`, `shipping_fee`, `sales_tax`, `digital`, `gift_card`, `store_credit`, `surcharge`.
    - `unit_price` (integer, required) — Unit price in cents
  - `total_amount` (integer, required) — Total order amount including tax in cents.
  - `total_tax` (integer, required) — Total tax of the order amount in cents.
  - `total_weight` (integer) — Total weight in grams
- `recipient` (object, required) — Information about the recipient
  - `care_of` (string)
  - `city` (string, required)
  - `company_name` (string) — Applicable only if recipient is a company
  - `country` (string, required) — 2 character ISO 3166 country format
  - `customer_type` (string) — B2C or B2B customer type. Note: does only indicate the type of customer, not if the address is residential or business. Enum: `person`, `organization`.
  - `email` (string)
  - `family_name` (string, required)
  - `given_name` (string, required)
  - `phone` (string) — E.164 international format
  - `postal_code` (string, required) — Normalized to country specifications
  - `region` (string) — Country specific region
  - `street_address` (string, required)
  - `street_address2` (string)
- `selected_shipping_option` (object, required)
  - `addons[]` (array<object>)
    - `data` (object, required) — Input from the user.
      - `selected` (boolean) — 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.
      - `text` (string) — 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.
    - `id` (string, required) — The `id` value from the `POST /shippingoptions` response.
    - `max_length` (integer) — The `max_length` value from the `POST /shippingoptions` response.
    - `preselected` (boolean) — The `preselected` value from the `POST /shippingoptions` response.
    - `price` (integer) — The `price` value from the `POST /shippingoptions` response.
    - `required` (boolean) — The `required` value from the `POST /shippingoptions` response.
    - `type` (string, required) — The `type` value from the `POST /shippingoptions` response. Type is one of: Enum: `sms`, `email`, `floor-number`, `apartment-number`, `entry-code`, `locker-code`, `additional-instructions`, `contactless-delivery`, `leave-outside-door`, `evening-delivery`, `daytime-delivery`, `expedited-packing`, `sustainable-packaging`, `carbon-compensated`, `indoor-home-delivery`, `assembly-at-pickup`, `package-removal`.
  - `carrier` (string) — The carrier for this option
  - `class` (string) — The shipping class for this option
  - `id` (string, required) — Optional TMS provided identifier
  - `location` (object)
    - `address` (object)
      - `city` (string, required)
      - `country` (string, required) — 2 character ISO 3166 country format
      - `postal_code` (string, required) — Normalized to country specifications
      - `region` (string) — Country specific region
      - `street_address` (string, required)
      - `street_address2` (string)
    - `coordinates` (object) — Geographical position in decimal degrees
      - `lat` (number, required) — Latitude in decimal degrees
      - `lng` (number, required) — Longitude in decimal degrees
    - `id` (string) — Optional TMS provided identifier
    - `name` (string) — Name of location
  - `price` (integer) — Total price for this option in cents, including extras and tax
  - `tax_rate` (integer) — Tax rate of shipping option.
  - `timeslot` (object)
    - `end` (string, required) — End of timeslot in ISO 8601 format
    - `id` (string) — Optional TMS provided identifier
    - `start` (string, required) — Start of timeslot in ISO 8601 format
  - `type` (string) — The type of shipping option
- `sender` (object) — Information about the sender. Should indicate from where the goods are dispatched. This object is optional and can be empty.
  - `address` (object)
    - `city` (string, required)
    - `country` (string, required) — 2 character ISO 3166 country format
    - `postal_code` (string, required) — Normalized to country specifications
    - `region` (string) — Country specific region
    - `street_address` (string, required)
    - `street_address2` (string)
  - `sender_id` (string) — 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_id` (string, required) — Unique Kustom shipping session id.

### Example request

```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"
}
```

## Responses

### 200

Shipment reservation updated successfully.

`application/vdn.klarna.shipping.get_shipment-v1+json`

- `additional_info` (string) — Any additional information that should be passed to a merchant from TMS can be provided here. Limit is 256 characters.
- `selected_shipping_option` (object, required)
  - `carrier` (string, required) — 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:
    Enum: `acs-courier`, `airmee`, `an-post`, `asendia`, `australia-post`, `austrian-post`, `bartolini`, `best`, `bpost`, `bring`, `bring-green`, `budbee`, `budbee-box`, `budcompaniett`, `bussgods`, `citymail`, `colis-prive`, `colissimo`, `collicare`, `correos`, `correos-express`, `crown-relocations`, `czech-post`, `dachser`, `danske-fragt`, `dao`, `deutsche-post`, `dhl`, `dhl-express`, `doorier`, `dooris`, `dpd`, `dsv`, `dynalogic`, `e2y`, `early-bird`, `emily-company`, `evri`, `fedex`, `fietskoeriers`, `generic`, `generic-postal`, `gls`, `gordon`, `helthjem`, `hoekstra`, `hrvatska-posta`, `in-time`, `instabikes`, `instabox`, `instabox-green`, `itella`, `kaukokiito`, `kiitolinja`, `laposte`, `leen-merken`, `lgt`, `magyar-posta`, `mat-se`, `matkahuolto`, `merchant`, `mioo-assembly-service`, `mx-transport`, `mondial-relay`, `mtd`, `netflux`, `ntex`, `oda`, `omniva`, `onroad`, `paack`, `packs`, `porterbuddy`, `post-it`, `post-luxembourg`, `posta-slovenija`, `posten-norge`, `posti`, `postnl`, `postnl-extra-home`, `postnord`, `professional-parcel-logistic`, `quick-pac`, `rapido`, `red-je-pakketje`, `relais-colis`, `royal-mail`, `safe-carrier-logistics`, `sagawa`, `schenker`, `skargarda`, `slovenska-posta`, `stuart`, `svosj`, `svosj-trial`, `swiss-post`, `swoopin`, `trunkrs`, `ups`, `urbit`, `urgent-cargus`, `van-spreuwel`, `wideroe-smart`, `wolt`, `yunda`, `zalando`.
  - `carrier_product` (object)
    - `addon_identifiers[]` (array<string>) — Product addon identifiers
    - `identifier` (string) — Carrier identifier/product code
    - `name` (string) — Carrier product name
- `shipment_id` (string, required) — The id of the (reserved) shipment
- `shipments[]` (array<object>)
  - `carrier` (string) — 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:
    Enum: `acs-courier`, `airmee`, `an-post`, `asendia`, `australia-post`, `austrian-post`, `bartolini`, `best`, `bpost`, `bring`, `bring-green`, `budbee`, `budbee-box`, `budcompaniett`, `bussgods`, `citymail`, `colis-prive`, `colissimo`, `collicare`, `correos`, `correos-express`, `crown-relocations`, `czech-post`, `dachser`, `danske-fragt`, `dao`, `deutsche-post`, `dhl`, `dhl-express`, `doorier`, `dooris`, `dpd`, `dsv`, `dynalogic`, `e2y`, `early-bird`, `emily-company`, `evri`, `fedex`, `fietskoeriers`, `generic`, `generic-postal`, `gls`, `gordon`, `helthjem`, `hoekstra`, `hrvatska-posta`, `in-time`, `instabikes`, `instabox`, `instabox-green`, `itella`, `kaukokiito`, `kiitolinja`, `laposte`, `leen-merken`, `lgt`, `magyar-posta`, `mat-se`, `matkahuolto`, `merchant`, `mioo-assembly-service`, `mx-transport`, `mondial-relay`, `mtd`, `netflux`, `ntex`, `oda`, `omniva`, `onroad`, `paack`, `packs`, `porterbuddy`, `post-it`, `post-luxembourg`, `posta-slovenija`, `posten-norge`, `posti`, `postnl`, `postnl-extra-home`, `postnord`, `professional-parcel-logistic`, `quick-pac`, `rapido`, `red-je-pakketje`, `relais-colis`, `royal-mail`, `safe-carrier-logistics`, `sagawa`, `schenker`, `skargarda`, `slovenska-posta`, `stuart`, `svosj`, `svosj-trial`, `swiss-post`, `swoopin`, `trunkrs`, `ups`, `urbit`, `urgent-cargus`, `van-spreuwel`, `wideroe-smart`, `wolt`, `yunda`, `zalando`.
  - `tracking_id` (string) — Carrier-specific tracking id.
  - `tracking_url` (string) — Carrier-specific URL to a web page where the consumer can see and make changes to their delivery.

```json
{
  "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>"
    }
  ]
}
```

### 400

The pre-shipment could not be updated, 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.

`application/vdn.klarna.shipping.get_shipment-v1+json`

- `failure_reason` (string)

```json
{
  "failure_reason": "shipping_option_not_available"
}
```

### 401

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

### 404

No such shipment (KSS will retry with a `POST /shipment` if this happens).