Shipping Options

DOCS

Last updated: Sept 23rd, 4:17pm

Important: Shipping Options is a limited-release feature available only to select merchants. For more information, reach out to your PayPal integration team.

Shipping Options is a feature of Smart Payment Buttons that extends your Smart Payment Buttons integration.

You can provide shipping and pickup options to your customers, within the Checkout flow, and then automatically update their shopping cart to reflect the shipping cost for the option they chose, for example, free shipping or 2-day express shipping.

Before you begin

You must know which PayPal API your app is integrated with. This guide assumes you are integrated with the JavaScript SDK using Orders API v2.

For legacy integrations, consider the following:

SetExpressCheckout - You cannot cannot initiate a SetExpressCheckout payment with Shipping Options using NVP or SOAP. You must make an Orders Patch call using your Express Checkout token to add shipping options, as you would with an order. See Customize Shipping Options for an example of updating shipping options.

Payments API v1 - See shipping_options in the Payments API v1 reference to create or update payments with shipping options.

Shipping options

This sample sets shipping options during order creation. Set options.type to SHIPPING.

1paypal.Buttons({
2    createOrder: function(data, actions) {
3        return actions.order.create({
4            purchase_units: [{
5                amount: {
6                    value: '0.01'
7                },
8                shipping: {
9                    options: [
10                        {
11                            id: 'SHIP1',
12                            type: 'SHIPPING',
13                            label: 'Free Shipping',
14                            selected: true,
15                            amount: {
16                                currency_code: 'USD',
17                                value: '0.00',
18                            }
19                        },
20                        {
21                           id: 'SHIP2',
22                            type: 'SHIPPING',
23                            label: '2-Day Shipping',
24                            selected: false,
25                            amount: {
26                                currency_code: 'USD',
27                                value: '4.00',
28                            }
29                        }
30                    ]
31                }
32            }]
33        });
34    }
35}).render('#paypal-button-container');

Shipping options for Orders API v2

Definitions for the shipping_option resource for Orders API v2.

`shipping_option`

Parameter	Type	Required	Description
`id`	string	Yes	A unique ID that identifies a payer-selected shipping option.
`label`	string	Yes	A description that the payer sees, which helps them choose an appropriate shipping option. For example, Free Shipping, USPS Priority Shipping, Expédition prioritaire USPS, or USPS yōuxiān fā huò. Localize this description to the payer's locale.
`type`	enum	No	The method by which the payer wants to get their items. The possible values are: `SHIPPING`. The payer intends to receive the items at a specified address. `PICKUP`. The payer intends to pick up the items at a specified address. For example, a store address.
`amount`	amount	No	The shipping cost for the selected option.
`selected`	boolean	Yes	If true it represents the shipping option that the merchant expects to be selected for the buyer when they view the shipping options within the PayPal Checkout experience. The selected shipping option must match the shipping cost in the order breakdown. Only one shipping option can be selected.

`amount`

Parameter	Type	Required	Description
`currency_code`	string	Yes	The three-character ISO-4217 currency code. PayPal does not support all currencies.
`value`	string	Yes	The amount. Includes the specified number of digits after decimal separator for the ISO-4217 currency code.

See the Orders API reference for more information about the Create order resource.

Pickup options

This sample sets pickup options during order creation. Set options.type to PICKUP.

1paypal.Buttons({
2    createOrder: function(data, actions) {
3        return actions.order.create({
4            purchase_units: [{
5                amount: {
6                    value: '0.01'
7                },
8                shipping: {
9                    options: [
10                        // ...
11                        {
12                           id: 'PICKUP0',
13                            type: 'PICKUP',
14                            label: 'Store Pickup',
15                            selected: false,
16                            amount: {
17                                currency_code: 'USD',
18                                value: '0.00',
19                            }
20                        }
21                    ]
22                }
23            }]
24        });
25    }
26}).render('#paypal-button-container');

The PICKUP option doesn't include a pickup address. You must patch the address in the final order and provide a pickup address so the buyer knows where to collect their items.

Important: In addition to patching the shipping address, you must also patch the shipping name with an S2S prefix.

The following sample makes a patch within the onApprove callback function to provide a PICKUP address.

Create an order and specify PICKUP for selectedOption.type.

Fetch the order within the onApprove callback function and check to see if the selected option type is PICKUP.

Update the name and pickup address for pickup orders.

1paypal.Buttons({
2    createOrder: function(data, actions) {
3        return actions.order.create({ /* ... */ });
4    },
5    onApprove: function(data, actions) {
6        return actions.order.get().then(order => {
7            // Get the selected option from the order
8            const selectedOption = (order.purchase_units[0].shipping.options || []).filter(option => option.selected).pop();
9
10            if (selectedOption.type !== 'PICKUP') {
11                return;
12            }
13
14            // Patch these two items:
15            // 1. The shipping name with the store name (prefixed with 'S2S')
16            // 2. The address of the store from where to pick up
17            return actions.order.patch([
18                {
19                    op: 'replace',
20                    path: '/purchase_units/@reference_id==\'default\'/shipping/name',
21                    value: {
22                        name: 'S2S Pickup Location Name',
23                    }
24                }
25                {
26                    op: 'replace',
27                    path: '/purchase_units/@reference_id==\'default\'/shipping/address',
28                    value: {
29                        address_line_1: '123 MyStore Ln',
30                        admin_area_2: 'San Jose',
31                        admin_area_1: 'CA',
32                        postal_code: '95131',
33                        country_code: 'US'
34                    }
35                }
36            ]);
37        }).then(() => {
38            return actions.order.capture();
39        });
40    }
41}).render('#paypal-button-container');

Customize options based on the buyer's address

Present personalized shipping options to your buyers using the onShippingAddressChange callback function.

This example includes a service that takes city, state, and postal code, and returns supported shipping options.

1paypal.Buttons({
2    createOrder: function(data, actions) {
3        return actions.order.create({ /* ... */ });
4    },
5    async onShippingAddressChange(data, actions) {
6        const options = {
7            method: "POST",
8            headers: {
9                "Content-Type": "application/json"
10            },
11            body: JSON.stringify({ /* ... */})
12        };
13        // send the order patch payload to the server (HOSTNAME) endpoint responsible for patching the order via the Orders V2 API
14        return fetch(
15            `${HOSTNAME}/api/order/${data.orderID}/addressChange`,
16            options
17        );
18    },
19    onApprove: function(data, actions) {
20        /* Pickup/Execute logic */
21    }
22}).render('#paypal-button-container');