On this page
No Headings
Support multiple shipping options
Last updated: June 26, 2026
DOCS
CURRENT
STANDARD
PARTNER
When buyers make changes to their shipping information, they can make 2 main types of updates:
- Changes to the merchant-provided shipping options.
- Changes to the shipping address.
Example: Venmo and PayPal shipping callbacks
Know before you code
PayPal Checkout
Complete the steps in Get started to get your sandbox account login information and access token from the Developer Dashboard.
This feature modifies an existing PayPal Checkout integration and uses the following:
- JavaScript SDK: Adds PayPal-supported payment methods.
- Orders REST API: Create, update, retrieve, authorize, and capture orders.
Shipping options limit
- The maximum number of items you can put in the shipping options array is 10.
Explore PayPal APIs with Postman
You can use Postman to explore and test PayPal APIs. Learn more in our Postman guide.
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
createOrdercallback 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 back-end code, use the item SKUs and quantities to calculate the item total.
- In your back-end code, define a list of shipping options to present to the buyer.
- In your back-end code, use the above information to define an order payload and use that to create an order with the Orders v2 API.
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<!-- Replace "test" with your own sandbox Business account app client ID -->
<script src="https://www.paypal.com/sdk/js?client-id=test¤cy=USD"></script>
<!-- Set up a container element for the button -->
<div id="paypal-button-container"></div>
<script>
paypal.Buttons({
createOrder() {
return fetch("/my-server/create-paypal-order", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
cart: [
{
sku: "YOUR_PRODUCT_STOCK_KEEPING_UNIT",
quantity: "YOUR_PRODUCT_QUANTITY",
},
]
})
})
.then((response) => response.json())
.then((order) => order.id);
}
}).render('#paypal-button-container');
</script>
</body>
</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.amount.value: A string denoting the price, formatted asX.XXamount.currency_code: The currency code to use, which reflects the currency code in thepurchase_units.amountobject.
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.
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<!-- Replace "test" with your own sandbox Business account app client ID -->
<script src="https://www.paypal.com/sdk/js?client-id=test¤cy=USD"></script>
<!-- Set up a container element for the button -->
<div id="paypal-button-container"></div>
<script>
paypal.Buttons({
onShippingAddressChange(data) {
return fetch("/my-server/patch-paypal-order", {
method: "PATCH",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
orderID: data.orderID,
shippingAddress: data.shippingAddress
})
})
},
}).render('#paypal-button-container');
</script>
</body>
</html>Next steps and customizations
Test integration
Test in the sandbox environment before going live.
Go live
Move from PayPal's production environment to go live.
JavaScript SDK
Customize your integration with script config parameters.