## Shippingratechange event

The `shippingratechange` event is triggered from an Express Checkout Element whenever the customer selects a new shipping rate in the payment interface.

This event is not available for Elements with Checkout Sessions (EwCS integrations). When using an Express Checkout Element with a Checkout Session, shipping rate changes are managed through the Checkout Session itself. You can update the session on your server after the customer completes their payment rather than responding to this event during the payment flow.

**Syntax:** `expressCheckoutElement.on(...)`

- `event` (string) **required**
  The name of the event.
In this case, `shippingratechange`.

- `handler` (function) **required**
  A callback function `handler(event) => void` you provide that's
called after the event is fired. After it's called, it passes an event object
with the following properties:

  - `elementType` ('expressCheckout') **required**
    The type of element the event is fired from, which is `expressCheckout` in this case.

  - `resolve` (function) **required**
    A function `resolve(payload) => void` that's called if the customer's shipping rate is valid.

    - `applePay` (object)
      Specify Apple Pay specific options. These are passed through to the Apple Pay API.

      - `recurringPaymentRequest` (object)
        Specify a request to set up a recurring payment. See the [Apple Pay documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepayrecurringpaymentrequest) for more details.

        - `paymentDescription` (string) **required**

        - `managementURL` (string) **required**

        - `regularBilling` (object) **required**

          - `amount` (number) **required**

          - `label` (string) **required**

          - `recurringPaymentStartDate` (Date)

          - `recurringPaymentEndDate` (Date)

          - `recurringPaymentIntervalUnit` ('year' | 'month' | 'day' | 'hour' | 'minute')

          - `recurringPaymentIntervalCount` (number)

        - `trialBilling` (object)

          - `amount` (number) **required**

          - `label` (string) **required**

          - `recurringPaymentStartDate` (Date)

          - `recurringPaymentEndDate` (Date)

          - `recurringPaymentIntervalUnit` ('year' | 'month' | 'day' | 'hour' | 'minute')

          - `recurringPaymentIntervalCount` (number)

      - `automaticReloadPaymentRequest` (object)
        Specify a request to set up an automatic reload payment. See the [Apple Pay documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepayautomaticreloadpaymentrequest) for more details.

        - `paymentDescription` (string) **required**

        - `managementURL` (string) **required**

        - `automaticReloadBilling` (object) **required**

          - `amount` (number) **required**

          - `label` (string) **required**

          - `automaticReloadPaymentThresholdAmount` (number) **required**

    - `lineItems` (array)
      An array of LineItem objects. These LineItems are shown as line items in the payment interface, if line items are supported.

      - `name` (string) **required**
        The name of the line item surfaced to the customer in the payment interface.

      - `amount` (number) **required**
        The amount in the currency's subunit (for example, cents, yen, etc.).

    - `shippingRates` (array)
      An array of ShippingRate objects. The first shipping rate listed appears in the payment interface as the default option.

      - `id` (string) **required**
        Unique identifier for the object.

      - `amount` (number) **required**
        The amount to charge for shipping.

      - `displayName` (string) **required**
        The name of the shipping rate, displayed to the customer in the payment interface.

      - `deliveryEstimate` (object | string)
        The estimated range for how long shipping takes, displayed to the customer in the payment interface.
We recommended using the object format, but you can use a string instead.

        - `maximum` (object)
          The upper bound of the estimated range. If empty, it represents no upper bound (for example, infinite).

          - `unit` ('hour' | 'day' | 'business_day' | 'week' | 'month')
            A unit of time.

          - `value` (number)
            Must be greater than 0.

        - `minimum` (object)
          The lower bound of the estimated range. If empty, it represents no lower bound.

          - `unit` ('hour' | 'day' | 'business_day' | 'week' | 'month')
            A unit of time.

          - `value` (number)
            Must be greater than 0.

  - `reject` (function) **required**
    A function `reject() => void` that's called if the customer's shipping rate is invalid.

  - `shippingRate` (object)
    The shipping rate selected by the customer.

    - `id` (string) **required**
      Unique identifier for the object.

    - `amount` (number) **required**
      The amount to charge for shipping.

    - `displayName` (string) **required**
      The name of the shipping rate, displayed to the customer in the payment interface.

    - `deliveryEstimate` (object | string)
      The estimated range for how long shipping takes, displayed to the customer in the payment interface.
We recommended using the object format, but you can use a string instead.

      - `maximum` (object)
        The upper bound of the estimated range. If empty, it represents no upper bound (for example, infinite).

        - `unit` ('hour' | 'day' | 'business_day' | 'week' | 'month')
          A unit of time.

        - `value` (number)
          Must be greater than 0.

      - `minimum` (object)
        The lower bound of the estimated range. If empty, it represents no lower bound.

        - `unit` ('hour' | 'day' | 'business_day' | 'week' | 'month')
          A unit of time.

        - `value` (number)
          Must be greater than 0.

### Handle 'shippingratechange' event

```js
expressCheckoutElement.on('shippingratechange', function(event) {
  var resolve = event.resolve;
  var shippingRate = event.shippingRate;
  // handle shippingratechange event

  // define payload and pass it into resolve
  var payload = {
    shippingRates: [
      shippingRate
    ]
  };

  // call event.resolve within 20 seconds
  resolve(payload);
});
```

```es_next
expressCheckoutElement.on('shippingratechange', (event) => {
  const {resolve, shippingRate} = event;
  // handle shippingratechange event

  // define payload and pass it into resolve
  const payload = {
    shippingRates: [
      shippingRate
    ]
  };

  // call event.resolve within 20 seconds
  resolve(payload);
});
```