Support multiple shipping options

docsCurrentLast updated: September 28th 2023, @ 7:37:45 am

When buyers make changes to their shipping information, there are two main types of updates they can make: changes to the merchant-provided shipping options and changes to the shipping address.

Know before you code

You'll need a standard payments integration.
The maximum number of items you can put in the shipping options array is 10.
Use Postman to explore and test PayPal APIs.

1. Shipping options changes

To offer your buyers the flexibility to choose their preferred delivery method, you can integrate shipping options. This can include in-store pickup, free shipping, and expedited shipping. Once a buyer has submitted their payment, you can verify their selected shipping option and ship accordingly.

Add shipping options

To provide shipping options to the buyer, complete the following steps:

Use the createOrder callback to make a fetch call to your server with information to uniquely identify the items being ordered. For example, you can pass an array of items containing the SKUs and quantities to represent the products the user has placed in their shopping cart on your ecommerce website.
In your backend code, use the item SKUs and quantities to calculate the item total.
In your backend code, define a list of shipping options to present to the buyer.
In your backend code, use the above information to define an order payload and use that to create an order with the v2 orders api

Frontend (HTML)
Backend (Node.js example)

1<!DOCTYPE html>
2<html>
3  <head>
4    <meta name="viewport" content="width=device-width, initial-scale=1">
5  </head>
6  <body>
7    <!-- Replace "test" with your own sandbox Business account app client ID -->
8    <script src="https://www.paypal.com/sdk/js?client-id=test&currency=USD"></script>
9    <!-- Set up a container element for the button -->
10    <div id="paypal-button-container"></div>
11    <script>
12      paypal.Buttons({
13        createOrder() {
14          return fetch("/my-server/create-paypal-order", {
15            method: "POST",
16            headers: {
17                "Content-Type": "application/json",
18            },
19            body: JSON.stringify({
20              cart: [
21                {
22                  sku: "YOUR_PRODUCT_STOCK_KEEPING_UNIT",
23                  quantity: "YOUR_PRODUCT_QUANTITY",
24                },
25              ]
26            })
27          })
28          .then((response) => response.json())
29          .then((order) => order.id);
30        }
31      }).render('#paypal-button-container');
32    </script>
33  </body>
34</html>

Values passed to shipping options array on the backend

id: A unique identifier for the shipping option.
label: The option presented to the payer in the dropdown menu.
type: An enum, "SHIPPING" or "PICKUP" to differentiate the type of shipping.
selected: A boolean to determine which option is selected by default.
amount: An object that contains the price of the shipping option.
- value: A string denoting the price, formatted as X.XX.
- currency_code: The currency code to use, which reflects the currency code in the purchase_units.amount object.

The order amount will automatically be updated based on the options chosen by the buyers, and you can use the onShippingOptionsChange() callback to update your own database with the new amount information.

paypal.Buttons({
  onShippingOptionsChange(data) {
    // data.selectedShippingOption contains the selected shipping option
    console.log("SELECTED_OPTION", data.selectedShippingOption);
  }
});

2. Shipping address change

When the shipping address changes, it may affect the shipping cost. In such a scenario, pass the shipping callback in the paypal.Buttons function.

If you have defined shipping.address in your order payload, the shipping callback onShippingAddressChange will be triggered when a different address is selected.

You can access the selected shipping address in the data parameter passed as follows:

paypal.Buttons({
  onShippingAddressChange(data) {
    // data.shippingAddress contains the selected shipping address
    console.log("SHIPPING_ADDRESS", data.shippingAddress);
  },
});

This example shows how to change the total price based on shipping address changes. The client-side code snippet sends data.shippingAddress to your server and the server-side code snippet looks up the new shippingAddress and changes the amount of the order.

Frontend (HTML)
Backend (Node.js example)

1<!DOCTYPE html>
2<html>
3  <head>
4    <meta name="viewport" content="width=device-width, initial-scale=1">
5  </head>
6  <body>
7    <!-- Replace "test" with your own sandbox Business account app client ID -->
8    <script src="https://www.paypal.com/sdk/js?client-id=test&currency=USD"></script>
9    <!-- Set up a container element for the button -->
10    <div id="paypal-button-container"></div>
11    <script>
12      paypal.Buttons({
13        onShippingAddressChange(data) {
14          return fetch("/my-server/patch-paypal-order", {
15            method: "PATCH",
16            headers: {
17                "Content-Type": "application/json",
18            },
19            body: JSON.stringify({
20              orderID: data.orderID,
21              shippingAddress: data.shippingAddress
22            })
23          })
24        },
25    }).render('#paypal-button-container');
26    </script>
27  </body>
28</html>

Next steps

Test in PayPal sandbox, then go live in PayPal's live environment.