Handling in-app shipping changes

[dtjones404]

Hi team, we’re looking for guidance on handling in-app shipping changes using the PaymentRequest API. It looks like the existing shippingaddresschange and shippingoptionchange events are both deprecated, so we're unsure if it's recommended to use them in our implementation. In our testing we found a way to handle bidirectional shipping callbacks using paymentmethodchange, but we're concerned about future breaking changes with that approach, since it doesn't seem like we're using the API as intended- we're essentially using changePaymentMethod() as a means of exchanging arbitrary data between the payment app and our SDK on the merchant page. For context, here's a repo with a minimal reproduction of the strategy we're considering.

A couple of questions:

1. What is the status of the shippingaddresschange and shippingoptionchange deprecations? Are there plans to remove them from future versions of the spec?
2. Currently paymentmethodchange allows for the exchange of arbitrary data between the payment app and the merchant page. Will this continue to be true in the future?

[rsolomakhin]

The shipping events need to be un-deprecated, because they are still implemented and being used. That's a spec issue, our bad!

The only possible change for paymentmethodchange event is to potentially remove the modifiers field, since we have not seen any legitimate use for that. If you avoid using that field, then you should be safe in passing data in paymentmethodchange.

cc @marcoscaceres

[ianbjacobs]

We've started the process of restoring address-related functionality (see the 24 September 2024 CR). The expectation is that these features are being restored to the specification, and that we will need to re-establish consensus for them (and get wide review) as part of returning to Recommendation with these features intact. Real-world usage is very helpful as part of that process.

[dtjones404]

Thanks for your responses @rsolomakhin and @ianbjacobs!

We are currently using modifiers to support this async communication with the partial address details (full demo):

// running on the merchant domain
paymentRequest.onpaymentmethodchange = (event) => {
  const details = event.methodDetails;
  const { eventName, eventPayload } = details;

  const eventHandler = eventHandlers[eventName];

  async function getResponsePromise() {
    // merchant async function to validate and patch order updates via PayPal's Orders API
    const response = await eventHandler?.(eventPayload);
    return {
      modifiers: [
        {
          data: { response },
          supportedMethods: paymentURL,
        },
      ],
    };
  }

  event.updateWith(getResponsePromise());
};

This allows the merchant to make an async API call on their end to validate the address, confirm they can ship to it, and update the order to reflect any changes to the shipping cost. We leverage event.updateWith to communicate to the payment app that the async work is complete, and whether the change is approved or rejected by the merchant. For us, we like modifiers as it solves our use case to pass arbitrary data through the PaymentRequest API. We see modifiers as a convenient low-level abstraction for the PaymentRequest API that can support many use cases because it is not overly prescriptive and does not enforce any shape on the data being passed.

Is this a valid use case for keeping modifiers as part of the spec?

We are open to switching to onshippingaddresschange and onshippingoptionchange, but we wanted to explain more about our use case first. PayPal's Orders API is the source of truth for an order as it is progresses through its lifecycle (unapproved, patch updates, buyer approval, transaction complete). It is redundant for us to store the payment information in the PaymentRequest details as well as on the server. Due to this, we use a dummy PaymentRequest details object, since it is not the source of truth for our transaction. Also, we have specific address requirements, for example we are not allowed to share address line number in the browser, since we consider that to be PII data, so it may be problematic for us if PaymentRequest is also enforcing a specific address schema. It's important for PayPal to own the address form as part of our payment UI, and we do not want the browser to add friction to the address collection process by prompting the user for permission to share address details.

Are there any docs or demos you can share with PaymentRequestEvent.changeShippingAddress? It's been difficult putting together a demo using those events since they're deprecated in the public docs.

[rsolomakhin]

Are there any docs or demos you can share with PaymentRequestEvent.changeShippingAddress?

We have a few demos at https://rsolomakhin.github.io/ under "Shipping, delivery, pickup". For example, see https://rsolomakhin.github.io/pr/us/.

Is this a valid use case for keeping modifiers as part of the spec?

We can consider keeping modifiers in the API for now. (Ideally, we would be able to serve this use case by moving data to be a top-level key in the PaymentDetailsUpdate dictionary, but that's a low priority enhancement.)

[dtjones404]

Thanks for the demos @rsolomakhin! We're evaluating our options and we'll get back to you soon.