Add shipping cost

Checkout Overview - Shipping costs

If you are shipping goods to your customer, you probably want to add a shipping cost to their order. If the shipping cost is a fixed amount regardless of the number of shopping cart items or the shipping address, you can simply add an item to the order that represents the shipping cost when you first create the payment object.

However, the shipping cost is likely to vary depending on the number of items in the shopping cart and the shipping address. In this case, the shipping cost cannot be calculated until your customer has provided a shipping address for the order.

Checkout enables you to manage shipping costs on the checkout page. This requires that both the frontend and backend interact with Checkout. The flowchart below shows the process involved in updating shipping costs based on the destination provided by your customer.

This guide shows you how to implement this functionality if you are using an embedded web integration. The actual calculation of the shipping cost is something you need to implement on your side, and is not provided in this guide.

Step 1: Create payment object (backend)

Checkout enables you to pause the checkout flow if a shipping cost is not specified. To enable this functionality, set the property merchantHandlesShippingCost to true when creating the payment object.

The following snippet demonstrates how to specify the merchantHandlesShippingCost property when creating the payment object:

{
  "order": {
      "items": [
      {

With the merchantHandlesShippingCost property set to true, Checkout will not proceed with the checkout until you add a shipping cost to the payment (see Step 3). But first, you need to track address changes in the frontend to calculate the new shipping cost.

Step 2: Listen to the "address-changed" event (frontend)

Next, you need to implement some more functionality in the frontend JavaScript to trigger a shipping cost calculation whenever the address changes on the checkout page. The frontend should:

1. Listen to the event named address-changed.
2. Freeze checkout using Checkout JS whenever an address changed event is triggered. This will temporarily disabled the checkout form.
3. Send a request to your backend that will compute a new shipping cost and update the payment object with Nexi Group.
4. Thaw checkout using Checkout JS. This will re-enable the checkout form so that your customer can continue to interact with the checkout.

The following JavaScript code will send a request to your backend, so that a new shipping cost can be calculated and added to the order for the payment object:

// Frontend JavaScript
// See Web integration guide for the complete JavaScript code

// 1. Listen to the address-changed event

During the time the checkout is frozen (disabled), the checkout will indicate that you are updating the shipping cost. Here is an example:

The message "Calculating shipping cost" indicates that the checkout is busy updating the order, which you will manage in the next step.

Step 3: Calculate and update shipping cost (backend)

It's time to implement a new HTTP endpoint for updating the shipping cost. It should:

1. Read the shipping address from the HTTP POST request sent by the JavaScript from the previous step.
2. Calculate a new shipping cost based on the address.
3. Add or modify the shipping cost attached to the payment object by using the update order method from the Payment API.

Below is an example of a script for updating the shipping cost. The actual calculation of the new shipping cost is not implemented correctly here. Instead, a random cost is generated. The order items are also mocked for this example:

<?php

// 1. Read and parse payload sent by frontend.
// The JSON object contains the paymentId and address information.

Let's walk through the code above:

1. Read the shipping address from the HTTP POST request sent by the JavaScript from the previous step.
2. Calculate a new shipping cost based on the address and generate a new JSON payload with the updated shipping cost. You need to define the methods computeShippingCost() and updateOrder(). The payload returned from updateOrder() should include the full order with the updated or new shipping cost. An example payload with shipping cost is shown below. The API reference also contains an example of a payload for the update order request.
3. Add or modify the shipping cost attached to the payment object by using the update order method from the Payment API.

The following JSON payload shows an example of a request body sent to the Payment API when adding shipping cost to an existing order:

{
  "amount": 57500,
  "items": [
    {

Step 4: Test the checkout flow

It's time to test the functionality for processing the shipping cost.

1. Load the checkout page.
2. Enter address information in the checkout form.
3. Whenever the address is updated, the JavaScript event handler should be triggered and send a request to the backend.
4. Verify that the checkout page displays the "Calculating shipping cost" message (as shown in the screenshot from Step 2).
5. Click the "Pay" button when the checkout has been reactivated and make sure that the checkout flow does not contain any errors.