Support multiple shipping options

docsCurrentLast updated: October 6th 2021, @ 7:10:14 pm


Integrate shipping options to allow your buyers to pick their items at a store or select from multiple ways to ship a product. When the buyer selects an address to ship a product, they can also select the way they want it delivered. When your buyer's payment is submitted, you can verify their selected option and ship accordingly.

Know before you code

You'll need a standard payments integration.

Shipping options

To provide shipping options to the buyer, add shipping options to the shipping object provided to actions.order.create().

API endpoint used: Create order

paypal.Buttons({
    createOrder: function(data, actions) {
        return actions.order.create({
            purchase_units: [{
                amount: {
                    value: "15.00",
                    currency_code: "USD"
                },
                shipping: {
                    options: [
                        {
                            id: "SHIP_123",
                            label: "Free Shipping",
                            type: "SHIPPING",
                            selected: true,
                            amount: {
                                value: "3.00",
                                currency_code: "USD"
                            }
                        },
                        {
                            id: "SHIP_456",
                            label: "Pick up in Store",
                            type: "PICKUP",
                            selected: false,
                            amount: {
                                value: "0.00",
                                currency_code: "USD"
                            }
                        }
                    ]
                }
            }]
        });
    }
});

Values passed to options

  • id: A unique identifier for the shipping option.
  • label: The option presented to the buyer 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 should reflect the currency code in the purchase_units.amount object.

Shipping callback with shipping options

The shipping callback is a method passed in the paypal.Buttons function to receive and handle changes the buyer has made to their shipping information. If you have passed any shipping.options to actions.order.create(), then whenever a new option is selected, the shipping callback, onShippingChange is called. You can access the selected options in the data parameter passed as follows:

    paypal.Buttons({
        onShippingChange: function(data, actions) {
            console.log("SELECTED_OPTION", data.selected_shipping_option); // data.selected_shipping_option contains the selected shipping option
        }
    })

This example shows how to change the total price based on different shipping options:

const baseAmount = "15.00";

paypal.Buttons({
    onShippingChange: function(data, actions) {
        // NOTE: data.selected_shipping_option_id contains the selected shipping ID
        // passed to the `actions.order.create()` call

        data.amount.value =
            parseFloat(baseAmount, 10) +
            parseFloat(data.selected_shipping_option.amount.value, 10);

        return actions.order.patch([{
            op:    "replace",
            path:  "/purchase_units/@reference_id=='default'/amount",
            amount: data.amount
        }]);
    }
});

Next steps

Test and go live

See also

JavaScript SDK reference