## The Express Checkout Element

The Express Checkout Element is
an embeddable component for accepting payments through one-click payment buttons.

## Create the Express Checkout Element

This method creates an instance of the Express Checkout Element.

**Syntax:** `elements.create(...)`

- `type` ('expressCheckout') **required**
  The type of Element being created, which is `expressCheckout` in this case.

- `options` (object)
  Options for creating the Express Checkout Element.

  - `allowedShippingCountries` (array)
    By default, the Express Checkout Element allows all countries for shipping.

You can specify which countries are allowed for shipping in the Express Checkout Element with a list of two-letter country codes.

  - `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)

      - `billingAgreement` (string)

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

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

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

      - `deferredBilling` (object) **required**

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

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

        - `deferredPaymentDate` (Date) **required**

      - `billingAgreement` (string)

      - `freeCancellationDate` (Date)
        If set, you must also supply a freeCancellationDateTimeZone.

      - `freeCancellationDateTimeZone` (string)
        If set, you must also supply a freeCancellationDate.

These are [tz](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) timezones such as `America/Los_Angeles`, `Europe/Dublin`, and `Asia/Singapore`.

    - `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**

      - `billingAgreement` (string)

  - `billingAddressRequired` (boolean)
    Controls whether the Express Checkout Element collects the billing address. The default value depends on your integration:

- If you pass `allowedShippingCountries`, `phoneNumberRequired`, `shippingAddressRequired`, `emailRequired`, `applePay`, `lineItems`, or `business` when creating the Express Checkout Element, `billingAddressRequired` defaults to false.
- Otherwise, `billingAddressRequired` defaults to true.

You can explicitly set `billingAddressRequired` to true or false to override the default behavior.

We highly recommend that you collect the billing address because it can be used to perform address verifications and block fraudulent payments.

  - `business` (object)
    Provide information about your business that's displayed in the Express Checkout Element.
This information will be retrieved from your Stripe account if it's not provided.

    - `name` (string)
      The name of your business. Your business name is used to signal to the customer who they're paying.

Klarna always retrieves the business name from your Stripe account, even when this option is set.

  - `buttonHeight` (number)
    By default, the height of the buttons are 44px.

You can override this to specify a custom button height in the range of 40px-55px.

  - `buttonTheme` (object)
    Specify the preferred button theme to use. By default, Elements determines the themes based on the specified [appearance option](/js/elements_object/create.md#stripe_elements-options-appearance).

    - `applePay` ('black' | 'white' | 'white-outline')

    - `googlePay` ('black' | 'white')

    - `paypal` ('gold' | 'blue' | 'silver' | 'white' | 'black')

    - `klarna` ('dark' | 'light' | 'outlined')

  - `buttonType` (object)
    Specify the preferred button type to display.

    - `applePay` ('add-money' | 'book' | 'buy' | 'check-out' | 'contribute' | 'donate' | 'order' | 'plain' | 'reload' | 'rent' | 'subscribe' | 'support' | 'tip' | 'top-up')
      Default is `plain`.

    - `googlePay` ('book' | 'buy' | 'checkout' | 'donate' | 'order' | 'pay' | 'plain' | 'subscribe')
      Default is `buy`.

    - `paypal` ('paypal' | 'checkout' | 'buynow' | 'pay')
      Default is `paypal`.

    - `klarna` ('continue' | 'pay')
      Default is `pay`.

  - `emailRequired` (boolean)
    Collect the customer's email by setting this option to `true`.

  - `layout` (object)
    Specify how the buttons are arranged in a grid-like layout in the Express Checkout Element.
Elements determines the layout by using certain factors, such as available space, number of buttons, and the defined `layout` object.

    - `maxColumns` (number)
      Defines the maximum number of columns the Express Checkout Element can use to render. Default is `0`, meaning unlimited.

    - `maxRows` (number)
      Defines the maximum number of rows the Express Checkout Element can use to render. Default is `0`, meaning unlimited.

    - `overflow` ('auto' | 'never')
      Specify whether or not to always hide the overflow menu or allow Elements to determine when to show the overflow menu. Default is `auto`.
You can't specify both `overflow: 'never'` and set `maxRows` to a number greater than 0.

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

    - `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.).

  - `paymentMethods` (object)
    By default, the Express Checkout Element displays all payment
methods possible as a result of your Dashboard configuration. This is the `auto` behavior.

If you don't want to show a given payment method as a payment option, set its
property in `paymentMethods` to `never`.

    - `amazonPay` ('auto' | 'never')

    - `applePay` ('always' | 'auto' | 'never')
      Apple Pay has additional configurations
that determine when Stripe can show it. By default, Apple Pay shows when the customer
is using a supported platform and when we determine it's advantageous for your conversion.
This is the `auto` behavior.

If you want to always show Apple Pay when the customer is using a supported platform,
you can set its property in `paymentMethods` to `always`. This causes Apple Pay to be shown in supported browsers even when the customer
isn't logged in to Apple Pay, resulting in a sign-in flow.

Apple Pay on desktop Chromium browsers is only supported on MacOS when its property in `paymentMethods` is set to `always`.

    - `googlePay` ('always' | 'auto' | 'never')
      Google Pay has additional configurations
that determine when Stripe can show it. By default, Google Pay shows when the customer
is using a supported platform and when we determine it's advantageous for your conversion.
This is the `auto` behavior.

If you want to always show Google Pay when the customer is using a supported platform,
you can set its property in `paymentMethods` to `always`. This causes Google Pay to be shown in supported browsers even when the customer
isn't logged in to Google Pay, resulting in a sign-in flow.

    - `link` ('auto' | 'never')

    - `paypal` ('auto' | 'never')

    - `klarna` ('auto' | 'never')

  - `paymentMethodOrder` (array)
    By default, the Express Checkout Element uses a dynamic ordering that optimizes payment method display for each user.

You can override the default order in which payment methods display in the Express Checkout Element with a list of payment method types.

If there are payment methods that will show that are not specified in `paymentMethodOrder`, they display after the payment methods you specify. If you specify payment methods that will not show, they are ignored.

  - `phoneNumberRequired` (boolean)
    Collect the customer's phone number by setting this option to `true`.

PayPal doesn't provide a phone number, even when this option is set to `true`.

Google Pay makes a best effort to return the phone number registered to the wallet, but doesn't guarantee it will be provided in all cases.

  - `shippingAddressRequired` (boolean)
    Collect the customer's shipping address by setting this option to `true`.

If `true`, you must also supply a valid `shippingRates` option in either the `create`, `click`, or `shippingaddresschange` events.

  - `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.

### Create an Express Checkout Element

```js
var expressCheckoutElement = elements.create('expressCheckout');
```

```es_next
const expressCheckoutElement = elements.create('expressCheckout');
```

## Get an Express Checkout Element

This method retrieves a previously created Express Checkout Element.

`elements.getElement('expressCheckout')` returns one of the following:

* An instance of an Express Checkout Element.
* `null`, when no Express Checkout Element has been created.

**Syntax:** `elements.getElement(...)`

- `type` ('expressCheckout') **required**
  The type of Element being retrieved, which is `expressCheckout` in this case.

### Get an Express Checkout Element

```js
var expressCheckoutElement = elements.getElement('expressCheckout');
```

```es_next
const expressCheckoutElement = elements.getElement('expressCheckout');
```

## Update an Express Checkout Element

Updates the options the [Express Checkout Element](/js/element/express_checkout_element.md)
was initialized with. Updates merge into the existing configuration.

**Syntax:** `element.update(...)`

- `options` (object)
  Options for updating the Express Checkout Element.

  - `allowedShippingCountries` (array)
    By default, the Express Checkout Element allows all countries for shipping.

You can specify which countries are allowed for shipping in the Express Checkout Element with a list of two-letter country codes.

  - `billingAddressRequired` (boolean)
    Controls whether the Express Checkout Element collects the billing address. The default value depends on your integration:

- If you pass `allowedShippingCountries`, `phoneNumberRequired`, `shippingAddressRequired`, `emailRequired`, `applePay`, `lineItems`, or `business` when creating the Express Checkout Element, `billingAddressRequired` defaults to false.
- Otherwise, `billingAddressRequired` defaults to true.

You can explicitly set `billingAddressRequired` to true or false to override the default behavior.

We highly recommend that you collect the billing address because it can be used to perform address verifications and block fraudulent payments.

  - `emailRequired` (boolean)
    Collect the customer's email by setting this option to `true`.

  - `layout` (object)
    Specify how the buttons are arranged in a grid-like layout in the Express Checkout Element.
Elements determines the layout by using certain factors, such as available space, number of buttons, and the defined `layout` object.

    - `maxColumns` (number)
      Defines the maximum number of columns the Express Checkout Element can use to render. Default is `0`, meaning unlimited.

    - `maxRows` (number)
      Defines the maximum number of rows the Express Checkout Element can use to render. Default is `0`, meaning unlimited.

    - `overflow` ('auto' | 'never')
      Specify whether or not to always hide the overflow menu or allow Elements to determine when to show the overflow menu. Default is `auto`.
You can't specify both `overflow: 'never'` and set `maxRows` to a number greater than 0.

  - `paymentMethodOrder` (array)
    By default, the Express Checkout Element uses a dynamic ordering that optimizes payment method display for each user.

You can override the default order in which payment methods display in the Express Checkout Element with a list of payment method types.

If there are payment methods that will show that are not specified in `paymentMethodOrder`, they display after the payment methods you specify. If you specify payment methods that will not show, they are ignored.

  - `phoneNumberRequired` (boolean)
    Collect the customer's phone number by setting this option to `true`.

PayPal doesn't provide a phone number, even when this option is set to `true`.

Google Pay makes a best effort to return the phone number registered to the wallet, but doesn't guarantee it will be provided in all cases.

  - `shippingAddressRequired` (boolean)
    Collect the customer's shipping address by setting this option to `true`.

If `true`, you must also supply a valid `shippingRates` option in either the `create`, `click`, or `shippingaddresschange` events.

### Update an Express Checkout Element

```js
var expressCheckoutElement = elements.getElement('expressCheckout');

expressCheckoutElement.update({
  layout: {
    maxColumns: 2,
    overflow: 'auto',
  },
});
```

```es_next
const expressCheckoutElement = elements.getElement('expressCheckout');

expressCheckoutElement.update({
  layout: {
    maxColumns: 2,
    overflow: 'auto',
  },
});
```

## Click event

The `click` event is triggered from an Express Checkout Element when the customer
clicks a payment button. Use this event to configure the payment interface.

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

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

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** 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.

  - `expressPaymentType` ('apple_pay' | 'google_pay' | 'amazon_pay' | 'paypal' | 'link' | 'klarna') **required**
    The payment method the customer checks out with.

  - `resolve` (function) **required**
    A function `resolve(payload) => void` that's called to show the payment interface. You must call this function within 1 second if you handle the `click` event.

    - `allowedShippingCountries (deprecated)` (array)
      _This parameter has been deprecated in favor of the `allowedShippingCountries` param on the [create](/js/elements_object/create_express_checkout_element.md#express_checkout_element_create-options-allowedShippingCountries) function._

By default, the Express Checkout Element allows all countries for shipping.

You can specify which countries are allowed for shipping in the Express Checkout Element with a list of two-letter country codes.

    - `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)

        - `billingAgreement` (string)

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

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

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

        - `deferredBilling` (object) **required**

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

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

          - `deferredPaymentDate` (Date) **required**

        - `billingAgreement` (string)

        - `freeCancellationDate` (Date)
          If set, you must also supply a freeCancellationDateTimeZone.

        - `freeCancellationDateTimeZone` (string)
          If set, you must also supply a freeCancellationDate.

These are [tz](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) timezones such as `America/Los_Angeles`, `Europe/Dublin`, and `Asia/Singapore`.

      - `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**

        - `billingAgreement` (string)

    - `billingAddressRequired (deprecated)` (boolean)
      _This parameter has been deprecated in favor of the `billingAddressRequired` param on the [create](/js/elements_object/create_express_checkout_element.md#express_checkout_element_create-options-billingAddressRequired) function._

By default, the Express Checkout Element collects the billing address. You can disable this by setting `billingAddressRequired` to `false`.

We highly recommend that you collect the billing address because it can be used to perform address verifications and block fraudulent payments.

    - `business (deprecated)` (object)
      _This parameter has been deprecated in favor of the `business` param on the [create](/js/elements_object/create_express_checkout_element.md#express_checkout_element_create-options-business) function._

Provide information about your business that's displayed in the Express Checkout Element.
This information will be retrieved from your Stripe account if it's not provided.

      - `name` (string)
        The name of your business. Your business name is used to signal to the customer who they're paying.

Klarna always retrieves the business name from your Stripe account, even when this option is set.

    - `emailRequired (deprecated)` (boolean)
      _This parameter has been deprecated in favor of the `emailRequired` param on the [create](/js/elements_object/create_express_checkout_element.md#express_checkout_element_create-options-emailRequired) function._

Collect the customer's email by setting this option to `true`.

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

      - `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.).

    - `phoneNumberRequired (deprecated)` (boolean)
      _This parameter has been deprecated in favor of the `phoneNumberRequired` param on the [create](/js/elements_object/create_express_checkout_element.md#express_checkout_element_create-options-phoneNumberRequired) function._

Collect the customer's phone number by setting this option to `true`.

PayPal doesn't provide a phone number, even when this option is set to `true`.

    - `shippingAddressRequired (deprecated)` (boolean)
      _This parameter has been deprecated in favor of the `shippingAddressRequired` param on the [create](/js/elements_object/create_express_checkout_element.md#express_checkout_element_create-options-shippingAddressRequired) function._

Collect the customer's shipping address by setting this option to `true`.

If `true`, you must also supply a valid `shippingRates` option in either the `create`, `click`, or `shippingaddresschange` events.

    - `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 to cancel the payment interface. You must call this function within 1 second if you handle the `click` event.

### Handle an express checkout element click event

```js
expressCheckoutElement.on('click', function(event) {
  // Handle click event
});
```

```es_next
expressCheckoutElement.on('click', (event) => {
  // Handle click event
});
```

## Confirm event

The `confirm` event is triggered from an Express Checkout Element when the customer
finalizes their payment. Use this event to trigger payment confirmation.

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

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

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

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

  - `expressPaymentType` ('apple_pay' | 'google_pay' | 'amazon_pay' | 'paypal' | 'link' | 'klarna') **required**
    The payment method the customer checks out with.

  - `paymentFailed` (function) **required**
    A function `paymentFailed(payload) => void` that's called if you're unable
to process the customer's payment.

    - `reason` ('fail' | 'invalid_shipping_address' | 'invalid_billing_address' | 'invalid_payment_data' | 'address_unserviceable')
      Default is `'fail'`. The payment interface might surface the reason
to provide a hint to the customer on why their payment failed.

    - `message` (string)
      A short, concise, localized error message to display on the payment sheet.
If none is provided, the payment sheet will display a generic error message for the given reason.

**Note:** Custom error messages may not be supported or may be truncated by certain wallets.

  - `billingDetails` (object)
    Object containing information about the customer's billing details.

    - `name` (string)
      The name of the customer.

    - `email` (string)
      The email address of the customer.

    - `phone` (string)
      The phone number of the customer.

    - `address` (string)
      The billing address of the customer.

**Note:** When using PayPal, the full billing address of the customer is not always exposed.
Typically, only the country code is passed back from PayPal.
To access the full billing address, you would need to request it from PayPal directly.

      - `line1` (string)

      - `line2` (string)

      - `city` (string)

      - `state` (string)

      - `postal_code` (string)

      - `country` (string)

  - `shippingAddress` (object)
    Object containing information about the customer's shipping address.

    - `name` (string)
      The name of the recipient.

    - `address` (string)
      The shipping address of the customer.

      - `line1` (string)

      - `line2` (string)

      - `city` (string)

      - `state` (string)

      - `postal_code` (string)

      - `country` (string)

  - `shippingRate` (object)
    Object containing information about the selected shipping rate.

    - `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 'confirm' event

```js
expressCheckoutElement.on('confirm', function(event) {
  // call Stripe function to initiate payment confirmation
  stripe.confirmPayment({
    elements,
    clientSecret,
    confirmParams: {
      return_url: 'https://example.com',
    },
  })
  .then(function(result) {
    if (result.error) {
      // Inform the customer that there's an error.
    }
  });
});
```

```es_next
expressCheckoutElement.on('confirm', (event) => {
  // call Stripe function to initiate payment confirmation
  const {error} = await stripe.confirmPayment({
    elements,
    clientSecret,
    confirmParams: {
      return_url: 'https://example.com',
    },
  });
});
```

## Cancel event

The `cancel` event is triggered from an Express Checkout Element when the payment interface is dismissed.

Note that in some browsers, the payment interface might be dismissed by the customer even after they authorize the payment.
This means that you might receive a `cancel` event after receiving a `confirm` event.
If you're using the `cancel` event as a hook for canceling the customer's order, make sure you also refund the payment that you just created.

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

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

- `handler` (function) **required**
  A callback function that you provide that's called after the event is fired.

### Handle 'cancel' event

```js
expressCheckoutElement.on('cancel', function() {
  // handle cancel event
});
```

```es_next
expressCheckoutElement.on('cancel', () => {
  // handle cancel event
});
```

## Shippingaddresschange event

The `shippingaddresschange` event is triggered from an Express Checkout Element whenever the customer selects a new address 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 address 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, `shippingaddresschange`.

- `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 recipient's shipping address 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 recipient's shipping address is invalid.

  - `name` (string)
    The name of the recipient.

  - `address` (string)
    The shipping address of the recipient.

To maintain privacy, browsers might anonymize the shipping address by removing sensitive information that isn't necessary to calculate shipping costs.
Depending on the country, some fields can be missing or partially redacted.
For example, the shipping address in the US can only contain a city, state, and ZIP code.
The full shipping address appears in the [confirm event](/js/elements_object/express_checkout_element_confirm_event.md#express_checkout_element_on_confirm-handler-shippingAddress) object after the purchase is confirmed in the browser’s payment interface.

    - `city` (string)

    - `state` (string)

    - `postal_code` (string)

    - `country` (string)

### Handle 'shippingaddresschange' event

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

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

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

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

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

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

## 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);
});
```