Default Shipping Item

It’s possible, and highly recommended, to pass a default shipping item in Initialize Payment and Update Items requests. In case of a failure, internally or in the external shipping broker, we fall back on the default shipping item which will always be available. By having a default shipping item, you guarantee that there will always be a shipping item in the customer’s cart at a certain price, regardless of any issues that may occur.

Adding a default shipping item

The default shipping item is passed in the body as an item in the *items***–**list, in any of the requests mentioned above. You must specify the value “SHI001” in the notes parameter for us to be able to detect that it’s a default shipping item. Refer to the example below for further clarification:

{
  "items": [
    {
      "description": "Product One",
      "notes": "Some notes",
      "amount": 50,
      "taxCode": "tax46",
      "taxAmount": 2,
      "quantity": 1,
      "articleNumber": "ASDASD86"
    },
    // Item below is a default shipping item (Notes: SHI001) ↓
    {
      "Description": "Shipping",
      "Notes": "SHI001",
      "Amount": 55.0,
      "TaxCode": "0",
      "TaxAmount": 9.8,
      "Quantity": 1
    }
  ]
}

Updating the default shipping item

It’s possible to pass a default shipping item in several requests during the checkout process, however, only the most recent one will be considered. Once a default shipping item is passed anywhere in the checkout process, it will always be available to fall back on.

If you want shipping to be free in some scenario, make sure to also update the price of the default shipping item accordingly, since it will be added to the cart total in case of a failure. For example in Update Items request:

{
  "items": [
    {
      "description": "Product One",
      "notes": "Some notes",
      "amount": 50,
      "taxCode": "tax46",
      "taxAmount": 2,
      "quantity": 1,
      "articleNumber": "ASDASD86"
    },
    {
      "Description": "Free Shipping",
      "Notes": "SHI001",
      "Amount": 0,
      "TaxCode": "0",
      "TaxAmount": 0,
      "Quantity": 1
    }
  ]
}

Replacing the default shipping item

If another shipping option is actively selected by the customer, it will replace the default shipping item in the cart and the notes parameter will have a value of “SHI002”. Even though it’s replaced in the cart, the default shipping item will still be available to fall back on in case of a failure.

Common Integration Guide Shipping Parameters