Update shipping

Enable shipping changes during checkout

SDKCurrentLast updated: October 5th 2021, @ 2:54:38 pm


You can enable your buyers to update their shipping options during checkout. They can:

  • Enter a new shipping address.
  • Select a local pick up option.
  • Select different shipping services.

If a buyer updates their shipping options during checkout, the order must also update the OnShippingChange callback.

Add the OnShippingChange callback

Depending on your integration, you need to add the 'OnShippingChange' to either the PaymentButton or PayPalCheckout.start().

PaymentButton

If your integration uses the default PayPalButton, add the OnShippingChange callback to PaymentButton.

    paymentButton.setup(
        ...
        OnShippingChange { shippingChangeData, shippingChangeActions ->

        }
    )
    paymentButton.setup(
        ...
        (shippingChangeData, shippingChangeActions) -> {

        }
    );

PayPalCheckout.start()

If you're integration programatically starts the SDK, add the 'OnShippingChange' callback to PayPalCheckout.start().

    PayPalCheckout.start(
        ...
        OnShippingChange { shippingChangeData, shippingChangeActions ->

        }
    )
    PayPalCheckout.start(
        ...
        (shippingChangeData, shippingChangeActions) -> {

        }
    );

Accept address changes

If a buyer changes their shipping address during checkout, their available shipping options and shipping cost could change.

Patch the new shipping options and shipping cost by passing PatchOrderRequest into patchOrder(). Also update the order Amount to reflect possible changes to the shipping cost.

    OnShippingChange { shippingChangeData, shippingChangeActions ->
        when(shippingChangeData.shippingChangeType) {
            ShippingChangeType.ADDRESS_CHANGE -> {
                // Updated shipping/pickup options
                val options: List = getShippingOptionsForAddress(shippingChangeData.shippingAddress)
                // Shipping amount of the selected option
                val updatedShippingAmount = options.find { it.selected }?.amount?.value

                val patchRequest = PatchOrderRequest(
                    PatchShippingOptions.Replace(options),
                    PatchAmount.Replace(
                        Amount(
                            currencyCode = CurrencyCode.USD,
                            breakdown = BreakDown(
                                itemTotal = itemTotal,
                                shipping = UnitAmount(
                                    currencyCode = CurrencyCode.USD,
                                    value = updatedShippingAmount
                                )
                            ),
                            value = newTotalvalue
                        )
                    )
                )
                shippingChangeActions.patchOrder(patchRequest) {
                    // Patch order completed
                }
            }
            ...
        }
    }
    (shippingChangeData, shippingChangeActions) -> {
        switch (shippingChangeData.getShippingChangeType()) {
            case ADDRESS_CHANGE:
                // Updated shipping/pickup options
                List options = getShippingOptionsForAddress(shippingChangeData.getShippingAddress());
                // Shipping amount of the selected option
                String updatedShippingAmount = options.stream()
                    .filter(Options::getSelected)
                    .findFirst().orElse(null).getAmount().getValue();

                PatchOrderRequest patchRequest = new PatchOrderRequest(
                    new PatchShippingOptions.Replace(options),
                    new PatchAmount.Replace(
                        new Amount(
                            CurrencyCode.USD,
                            new BreakDown(
                                itemTotal,
                                new UnitAmount(
                                    CurrencyCode.USD,
                                    updatedShippingAmount
                                )
                            ),
                            newTotalValue
                        )
                    )
                );

                shippingChangeActions.patchOrder(patchRequest, () -> {
                    // Patch order completed
                });
                ...
        }
    }

Reject address changes

If a buyer changes their shipping address to an address that isn't supported, invoke the shippingChangeActions.reject() function. This displays an error to the buyer that requires them to change their shipping address in order to proceed with the checkout.

    OnShippingChange { shippingChangeData, shippingChangeActions ->
        when (shippingChangeData.shippingChangeType) {
            ShippingChangeType.ADDRESS_CHANGE -> {
                // Example - Reject all shipping addresses outside of the US
                if (shippingChangeData.shippingAddress.countryCode != "US") {
                    shippingChangeActions.reject()
                }
            }
        }
    }
    (shippingChangeData, shippingChangeActions) -> {
        switch (shippingChangeData.getShippingChangeType()) {
            case ADDRESS_CHANGE:
                // Example - Reject all shipping addresses outside of the US
                if (shippingChangeData.getShippingAddress().getCountryCode() != "US") {
                    shippingChangeActions.reject();
                }
        }
    }

Update list of shipping options

If a buyer successfully updates their shipping address or selects local pick up, notify the SDK by calling the patchOrder(patchOrderRequest: PatchOrderRequest) function.

Accept shipping changes

Selecting a different shipping service or local pick up option during checkout, updates shippingChangeData. Pass the options and the updated shipping amount into PatchOrderRequest.

OnShippingChange { shippingChangeData, shippingChangeActions ->
    when (shippingChangeData.shippingChangeType) {
        ...
        ShippingChangeType.OPTION_CHANGE -> {
            val options: List = shippingChangeData.shippingOptions
            val updatedShippingAmount = shippingChangeData.selectedShippingOption?.amount?.value

            val patchRequest = PatchOrderRequest(
                PatchShippingOptions.Replace(options),
                PatchAmount.Replace(
                    Amount(
                        currencyCode = CurrencyCode.USD,
                        breakdown = BreakDown(
                            itemTotal = itemTotal,
                            shipping = UnitAmount(
                                currencyCode = CurrencyCode.USD,
                                value = updatedShippingAmount
                            )
                        ),
                        value = newTotalvalue
                    )
                )
            )
            shippingChangeActions.patchOrder(patchRequest) {
                // Patch order completed
            }
        }
    }
}
    (shippingChangeData, shippingChangeActions) -> {
        switch (shippingChangeData.getShippingChangeType()) {
            ...
            case OPTION_CHANGE:
                // Updated shipping/pickup options
                List options = shippingChangeData.getShippingOptions();
                // Shipping amount of the selected option
                String updatedShippingAmount = shippingChangeData.getSelectedShippingOption().getAmount().getValue();

                PatchOrderRequest patchRequest = new PatchOrderRequest(
                    new PatchShippingOptions.Replace(options),
                    new PatchAmount.Replace(
                        new Amount(
                            CurrencyCode.USD,
                            new BreakDown(
                                itemTotal,
                                new UnitAmount(
                                    CurrencyCode.USD,
                                    updatedShippingAmount
                                )
                            ),
                            newTotalValue
                        )
                    )
                );

                shippingChangeActions.patchOrder(patchRequest, () -> {
                    // Patch order completed
                });
        }
    }