## Elements with the Checkout Sessions API

Build an online checkout page using React, Stripe Elements, and the Checkout Sessions API.

See [build a checkout page](/checkout/custom/quickstart.md) for steps on using Elements with the Checkout Sessions API.

The following Stripe.js methods are available to use as part of your integration.

## Initialize Checkout

This method initializes Checkout.

This method returns a `Checkout` instance.

**Syntax:** `stripe.initCheckout(...)`

- `options` (object)
  Checkout initialization options.

  - `clientSecret` (Promise<string> | string) **required**
    The Checkout Session [client secret](/api/checkout/sessions/object.md#checkout_session_object-client_secret) or a promise that resolves to the client secret.

  - `elementsOptions` (object)
    A set of options to configure Elements created with Checkout.

    - `appearance` (object)
      Match the design of your site with the [appearance option](/elements/appearance-api.md).
The layout of each Element stays consistent, but you can modify colors, fonts, borders, padding, and more.

    - `loader` ('auto' | 'always' | 'never')
      Display skeleton loader UI while waiting for Elements to fully load after they're mounted.
Default is `'auto'` (Stripe determines whether or not to show a loader UI).

    - `fonts` (array)
      An array of custom fonts that elements created from the `Elements` object can use. You can specify fonts as [CssFontSource](#css_font_source_object) or [CustomFontSource](#custom_font_source_object) objects.

    - `savedPaymentMethod` (object)
      Options to configure what Elements displays when used to [Save payment details during payment](/payments/checkout/save-during-payment.md).

      - `enableRedisplay` ('auto' | 'never')
        Toggle if Elements redisplays Customer saved Payment Methods. Default is `'auto'`. Prior to Clover, this defaulted to `'never'`.

      - `enableSave` ('auto' | 'never')
        Toggle if the Payment Element collects consent to save a Customer's Payment Methods. Default is `'auto'`. Prior to Clover, this defaulted to `'never'`.

    - `syncAddressCheckbox` ('billing' | 'shipping' | 'none')
      Used with the [Address Element](/elements/address-element.md).

The `syncAddressCheckbox` parameter configures which Address Element to show the checkbox.

The checkbox allows the customer the option to sync billing and shipping addresses when both Billing and Shipping Address Elements are used in a single Elements instance.

  - `adaptivePricing` (object)
    Options for [Adaptive Pricing](/payments/currencies/localize-prices/adaptive-pricing.md?payment-ui=embedded-components).

    - `allowed` (boolean)
      Whether Adaptive Pricing can be used with this integration. Default is `false`.
[Additional setup](/payments/currencies/localize-prices/adaptive-pricing.md?payment-ui=embedded-components) is required before you can use Adaptive Pricing with embedded components.

  - `defaultValues` (object)
    If customer details are already known, this option may be passed to prefill the Checkout Session and related elements.

    - `billingAddress` (object)
      The Customer's billing address.

      - `name` (optional string)
        Full name.

      - `address` (optional object)
        Address.

        - `country` (string) **required**
          Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).

        - `line1` (optional string)
          Address line 1 (e.g., street, PO Box, or company name).

        - `line2` (optional string)
          Address line 2 (e.g., apartment, suite, unit, or building).

        - `city` (optional string)
          City, district, suburb, town, or village.

        - `postal_code` (optional string)
          ZIP or postal code.

        - `state` (optional string)
          State, county, province, or region.

    - `shippingAddress` (object)
      The Customer's shipping address.

      - `name` (optional string)
        Full name.

      - `address` (optional object)
        Address.

        - `country` (string) **required**
          Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).

        - `line1` (string) **required**
          Address line 1 (e.g., street, PO Box, or company name).

        - `line2` (optional string)
          Address line 2 (e.g., apartment, suite, unit, or building).

        - `city` (optional string)
          City, district, suburb, town, or village.

        - `postal_code` (optional string)
          ZIP or postal code.

        - `state` (optional string)
          State, county, province, or region.

    - `email` (string)
      The Customer's email address.

    - `phoneNumber` (string)
      The Customer's phone number.

### Initialize Checkout

```js
const clientSecret = createCheckoutSession();
const checkout = stripe.initCheckout({
  clientSecret,
});
```

```es_next
const clientSecret = await createCheckoutSession();
const checkout = stripe.initCheckout({
  clientSecret,
});
```

## Checkout actions

After calling [initCheckout](/js/custom_checkout/init.md), use `loadActions()` to access methods for reading and manipulating [Checkout Sessions](/api/checkout/sessions.md).

This method returns a `Promise` that resolves with an object with the following shape:

  * `{type: "error", error: { message: string }}`
  * `{type: "success", actions: object }`

On success, the `actions` object provides methods to interact with the [Checkout Session](/api/checkout/sessions).

**Syntax:** `checkout.loadActions(...)`


### Checkout actions

```js
const checkout = stripe.initCheckout({
  clientSecret: 'CLIENT_SECRET',
});
checkout.loadActions().then(function(result) {
  if (result.type === 'success') {
    // Use the actions object to interact with the Checkout Session
    const actions = result.actions;
  }
}
```

```es_next
const checkout = stripe.initCheckout({
  clientSecret: 'CLIENT_SECRET',
});
const result = await checkout.loadActions();
if (result.type === 'success') {
  // Use the actions object to interact with the Checkout Session
  const actions = result.actions;
}
```

## Read session data

This method returns an object that contains data about the Checkout Session.

This method returns a [Session object](/js/custom_checkout/session_object).

**Syntax:** `actions.getSession(...)`

### Read session data

```js
const checkout = stripe.initCheckout({
  clientSecret: 'CLIENT_SECRET',
});
checkout.loadActions().then(function(result) {
  if (result.type === 'success') {
    // Use the actions object to interact with the Checkout Session
    const actions = result.actions;
    var session = actions.getSession();
  }
}
```

```es_next
const checkout = stripe.initCheckout({
  clientSecret: 'CLIENT_SECRET',
});
const result = await checkout.loadActions();
if (result.type === 'success') {
  // Use the actions object to interact with the Checkout Session
  const actions = result.actions;
  const session = actions.getSession();
}
```

## Apply a promotion code

Use this method to apply a promotion code that your customer enters.

This method returns a `Promise` that resolves with an object containing the following fields:
* `type`: one of either `"success"` or `"error"`
* `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state.
* `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer.

**Syntax:** `actions.applyPromotionCode(...)`

- `promotionCode` (string) **required**
  The promotion code to apply to the Checkout Session.

### Apply a promotion code

```jsx
actions.applyPromotionCode('PROMOTION_CODE');
```

## Remove a promotion code

Use this method to remove the currently applied promotion code, if applicable.

This method returns a `Promise` that resolves with an object containing the following fields:
* `type`: one of either `"success"` or `"error"`
* `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state.
* `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer.

**Syntax:** `actions.removePromotionCode(...)`


### Remove a promotion code

```jsx
actions.removePromotionCode();
```

## Update the Customer's shipping address

Use this method to update the Customer's shipping address. If your integration uses the [Express Checkout Element](/elements/express-checkout-element.md), the shipping address is collected directly from the wallet and the value set by `updateShippingAddress` is not used for express checkout payments.

This method returns a `Promise` that resolves with an object containing the following fields:
* `type`: one of either `"success"` or `"error"`
* `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state.
* `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer.

**Syntax:** `actions.updateShippingAddress(...)`

- `shippingAddress` (nullable object) **required**
  New shipping address for the Customer.

  - `name` (optional string)
    Full name.

  - `address` (optional object)
    Address.

    - `country` (string) **required**
      Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).

    - `line1` (string) **required**
      Address line 1 (e.g., street, PO Box, or company name).

    - `line2` (optional string)
      Address line 2 (e.g., apartment, suite, unit, or building).

    - `city` (optional string)
      City, district, suburb, town, or village.

    - `postal_code` (optional string)
      ZIP or postal code.

    - `state` (optional string)
      State, county, province, or region.

### Update the Customer's shipping address

```jsx
actions.updateShippingAddress({
  name: 'Jenny Rosen',
  address: {
    line1: '27 Fredrick Ave',
    city: 'Brothers',
    state: 'OR',
    postal_code: '97712',
    country: 'US',
  }
});
```

## Update the Customer's billing address

Use this method to update the Customer's billing address. If your integration uses the [Express Checkout Element](/elements/express-checkout-element.md), the billing address is collected directly from the wallet and the value set by `updateBillingAddress` is not used for express checkout payments.

This method returns a `Promise` that resolves with an object containing the following fields:
* `type`: one of either `"success"` or `"error"`
* `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state.
* `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer.

**Syntax:** `actions.updateBillingAddress(...)`

- `billingAddress` (nullable object) **required**
  New billing information for the Customer.

  - `name` (optional string)
    Full name.

  - `address` (optional object)
    Address.

    - `country` (string) **required**
      Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).

    - `line1` (optional string)
      Address line 1 (e.g., street, PO Box, or company name).

    - `line2` (optional string)
      Address line 2 (e.g., apartment, suite, unit, or building).

    - `city` (optional string)
      City, district, suburb, town, or village.

    - `postal_code` (optional string)
      ZIP or postal code.

    - `state` (optional string)
      State, county, province, or region.

### Update the Customer's billing address

```jsx
actions.updateBillingAddress({
  name: 'Jenny Rosen',
  address: {
    line1: '27 Fredrick Ave',
    city: 'Brothers',
    state: 'OR',
    postal_code: '97712',
    country: 'US',
  }
});
```

## Update the Customer's email address

Use this method to update the Customer's email address. If your integration uses [Link](/payments/link.md) and you do not provide an email during Checkout Session creation, you must call `updateEmail` for Link to appear as a payment option for returning users. If your integration uses the [Express Checkout Element](/elements/express-checkout-element.md), the email address is collected directly from the wallet and the value set by `updateEmail` is not used for express checkout payments.

This method returns a `Promise` that resolves with an object containing the following fields:
* `type`: one of either `"success"` or `"error"`
* `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state.
* `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer.

**Syntax:** `actions.updateEmail(...)`

- `email` (nullable string) **required**
  The Customer's email address.

### Update the Customer's email address

```jsx
actions.updateEmail('jenny.rosen@example.com');
```

## Update the Customer's phone number

Use this method to update the Customer's phone number. If your integration uses the [Express Checkout Element](/elements/express-checkout-element.md), the phone number is collected directly from the wallet and the value set by `updatePhoneNumber` is not used for express checkout payments.

This method returns a `Promise` that resolves with an object containing the following fields:
* `type`: one of either `"success"` or `"error"`
* `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state.
* `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer.

**Syntax:** `actions.updatePhoneNumber(...)`

- `phoneNumber` (nullable string) **required**
  The Customer's phone number.

### Update the Customer's phone number

```jsx
actions.updatePhoneNumber('5554242424');
```

## Update the Customer's business name and tax ID

Use this method to update the Customer's business name and tax ID.

This method returns a `Promise` that resolves with an object containing the following fields:
* `type`: one of either `"success"` or `"error"`
* `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state.
* `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer.

**Syntax:** `actions.updateTaxIdInfo(...)`

- `taxIdInfo`
  The Customer's tax ID information including the business name and tax ID.

  - `businessName` (nullable string) **required**
    The Customer's business name.

  - `taxId` **required**
    The Customer's tax ID.

    - `type` **required**
      One of [the supported tax ID types](/tax/checkout/tax-ids?payment-ui=embedded-components.md#supported-types)

    - `value` (nullable string) **required**
      The value of the tax ID.

### Update the Customer's business name and tax ID

```jsx
actions.updateTaxIdInfo({
  businessName: 'Acme, Inc.',
  taxID: {
    type: 'eu_vat',
    value: 'DK12345678'
  }
});
```

## Update line item quantities

Use this method to change the quantity of a line item.

This method returns a `Promise` that resolves with an object containing the following fields:
* `type`: one of either `"success"` or `"error"`
* `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state.
* `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer.

**Syntax:** `actions.updateLineItemQuantity(...)`

- `options` (object) **required**
  Options for `updateLineItemQuantity`.

  - `lineItem` (string) **required**
    The [ID](/js/custom_checkout/session_object.md#custom_checkout_session_object-lineItems-id) of the line item to update.

  - `quantity` (integer) **required**
    The new quantity of the line item.

### Update line item quantities

```jsx
actions.updateLineItemQuantity({
  lineItem: 'LINE_ITEM_ID',
  quantity: 2,
});
```

## Update the selected shipping option

Use this method to update the selected shipping option. See [shippingOptions](/js/custom_checkout/session_object.md#custom_checkout_session_object-shippingOptions) for a list of the available shipping options.

This method returns a `Promise` that resolves with an object containing the following fields:
* `type`: one of either `"success"` or `"error"`
* `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state.
* `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer.

**Syntax:** `actions.updateShippingOption(...)`

- `shippingOption` (string)
  The [ID](/js/custom_checkout/session_object.md#custom_checkout_session_object-shippingOptions-id) of the shipping option to select.

### Update the selected shipping option

```jsx
actions.updateShippingOption('SHIPPING_OPTION_ID');
```

## Confirm the Checkout Session

Use this method to confirm the Checkout Session.

You must either read [total.total.amount](/js/custom_checkout/session_object.md#custom_checkout_session_object-total-total-amount) or each of [total.total.minorUnitsAmount](/js/custom_checkout/session_object.md#custom_checkout_session_object-total-total-minorUnitsAmount) and [currency](/js/custom_checkout/session_object.md#custom_checkout_session_object-currency) and [minorUnitsAmountDivisor](/js/custom_checkout/session_object.md#custom_checkout_session_object-minorUnitsAmountDivisor) from the checkout object and display in your UI, otherwise an error will be thrown. This helps keep your checkout page in sync as the Checkout Session updates, including adding future Stripe features, with minimal UI code changes.

This method returns a `Promise` that resolves with an object containing the following fields:
* `type`: one of either `"success"` or `"error"`
* `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state.
* `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer.

**Syntax:** `actions.confirm(...)`

- `options` (object)
  Options for `confirm`.

  - `returnUrl` (string)
    The URL to redirect your customer to after they authenticate or cancel their payment on the payment method’s app or site. This parameter is only required if you didn't specify the  `return_url` when creating the Checkout Session.

  - `paymentMethod` (string)
    The ID of a previously collected [PaymentMethod](/api/payment_methods/object.md) to use for confirmation.

When this option is provided, Custom Checkout will ignore the payment method collected by the PaymentElement and attempt confirmation using the provided PaymentMethod.

  - `savePaymentMethod` (boolean)
    Whether your Customer has provided consent to save the payment method for future purchases.

Learn how to [save payment methods](/checkout/custom-checkout/save-payment-methods-checkout.md).

  - `redirect` ('always' | 'if_required')
    By default, `confirm` will always redirect to your `returnUrl` after a successful confirmation.  If you set `redirect: "if_required"`, then `confirm` will only redirect if your user chooses a redirect-based payment method.

  - `email` (string)
    The Customer's email address.

If provided, this value overrides any values previously set using [updateEmail](/js/custom_checkout/update_email.md).

  - `phoneNumber` (string)
    The Customer's phone number.

If provided, this value overrides any values previously set using [updatePhoneNumber](/js/custom_checkout/update_phone_number.md).

  - `billingAddress` (object)
    The Customer's billing address.

If provided, this value overrides any values previously set using [updateBillingAddress](/js/custom_checkout/update_billing_address.md).

    - `name` (optional string)
      Full name.

    - `address` (optional object)
      Address.

      - `country` (string) **required**
        Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).

      - `line1` (optional string)
        Address line 1 (e.g., street, PO Box, or company name).

      - `line2` (optional string)
        Address line 2 (e.g., apartment, suite, unit, or building).

      - `city` (optional string)
        City, district, suburb, town, or village.

      - `postal_code` (optional string)
        ZIP or postal code.

      - `state` (optional string)
        State, county, province, or region.

  - `shippingAddress` (object)
    The Customer's shipping address.

If provided, this value overrides any values previously set using [updateShippingAddress](/js/custom_checkout/update_shipping_address.md).

    - `name` (optional string)
      Full name.

    - `address` (optional object)
      Address.

      - `country` (string) **required**
        Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).

      - `line1` (string) **required**
        Address line 1 (e.g., street, PO Box, or company name).

      - `line2` (optional string)
        Address line 2 (e.g., apartment, suite, unit, or building).

      - `city` (optional string)
        City, district, suburb, town, or village.

      - `postal_code` (optional string)
        ZIP or postal code.

      - `state` (optional string)
        State, county, province, or region.

  - `expressCheckoutConfirmEvent` (object)
    The [event object](/js/elements_object/express_checkout_element_confirm_event.md#express_checkout_element_on_confirm-handler) passed to your Express Checkout Element `confirm` handler.

### Confirm the Checkout Session

```jsx
actions.confirm({
  returnUrl: 'RETURN_URL',
});
```

## Run server update

Use this method to wrap an async function that makes a request to your server to update the Checkout Session.

> `runServerUpdate` enforces a 20-second timeout for your update function. If your function doesn't resolve within 20 seconds, `runServerUpdate` returns an error. Wrap `runServerUpdate` calls in `try`/`catch` blocks to handle any errors.

This method returns a `Promise` that resolves with an object containing the following fields:
* `type`: one of either `"success"` or `"error"`
* `session`: only populated when `type` is `"success"`. Contains a [Session](/js/custom_checkout/session_object) instance representing the updated state.
* `error`: only populated when `type` is `"error"`. Contains an object with a string `message` field which can be displayed to your customer.

**Syntax:** `actions.runServerUpdate(...)`

- `userFunction` (function) **required**
  An async function to make a request to your server to update the Checkout Session.

### Run server update

```jsx
actions.runServerUpdate(
  () => {
    return fetch('/update-checkout-session', {
      method: 'POST',
      body: JSON.stringify({checkoutSessionId: '{CHECKOUT_SESSION_ID}'}),
    });
  }
);
```

## The Session object

The Session object is a view of the [Checkout Session](/api/checkout/sessions/object.md)
API object and represents your customer's session on your checkout page.

Because data can change over the lifecycle of a session, avoid storing
a reference to the Session object. Instead, call `session()` to
retrieve the current value and listen to the [change event](/js/custom_checkout/change_event.md)
to subscribe to updates.

- `id` (string)
  The ID of the Checkout Session.

- `billingAddress` (nullable object)
  Billing details of the Customer.

  - `name` (nullable string)
    Full name.

  - `address` (nullable object)
    Address.

    - `country` (string)
      Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).

    - `line1` (nullable string)
      Address line 1 (e.g., street, PO Box, or company name).

    - `line2` (nullable string)
      Address line 2 (e.g., apartment, suite, unit, or building).

    - `city` (nullable string)
      City, district, suburb, town, or village.

    - `postal_code` (nullable string)
      ZIP or postal code.

    - `state` (nullable string)
      State, county, province, or region.

- `businessName` (nullable string)
  The business name as configured in the Business Public Details settings of your Stripe account.

- `canConfirm` (boolean)
  Whether the Checkout Session has collected enough data to confirm. Use this field to indicate to your customer if they can proceed, such as disabling the pay button.

- `currency` (enum)
  Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in
lowercase. Must be a [supported currency](/currencies.md).

- `currencyOptions` (nullable array of objects)
  The currency options available on the Checkout Session when using [Adaptive Pricing](/checkout/custom-checkout/adaptive-pricing.md).

  - `amount` (string)
    A formatted string representing the total amount in the source currency, including currency symbols.

  - `minorUnitsAmount` (integer)
    An integer representing the total amount in the source currency in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

  - `currency` (enum)
    Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase.

  - `currencyConversion` (optional object)
    Currency conversion details. This is only present for the customer currency.

    - `fxRate` (decimal string)
      The exchange rate used to convert source currency amounts to customer currency amounts.

    - `sourceCurrency` (enum)
      The creation currency of the Checkout Session before localization.

- `discountAmounts` (array of objects)
  The aggregate amounts calculated per discount for all line items.

  - `amount` (string)
    A formatted string representing the discount amount, including currency symbols.

  - `minorUnitsAmount` (integer)
    An integer representing the discount amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

  - `displayName` (string)
    A user-facing description of the discount.

  - `promotionCode` (nullable string)
    The customer-facing promotion code that was used to apply this discount, if any.

  - `recurring` (nullable object)
    Details of how the discount applies to recurring payments.

    - `type` (enum)
      One of `forever` or `repeating`.
* `forever`: Applies to all charges from a subscription with this coupon applied.
* `repeating`: Applies to charges in the first `durationInMonths` months from a subscription with this coupon applied.

    - `durationInMonths` (nullable integer)
      If `duration` is `repeating`, the number of months the coupon applies. Null otherwise.

  - `percentOff` (nullable integer)
    An integer representing the discount amount as a percentage.

- `email` (nullable string)
  The Customer's email address.

- `lastPaymentError` (nullable object)
  The error encountered the last time the Checkout Session was confirmed.

  - `message` (string)
    An error message to be displayed to the customer.

- `lineItems` (array of objects)
  A list of items the customer is purchasing.

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

  - `subtotal` (nullable object)
    Total before any discounts or exclusive taxes are applied.

    - `amount` (string)
      A formatted string representing the subtotal amount, including currency symbols.

    - `minorUnitsAmount` (integer)
      An integer representing the subtotal amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

  - `discount` (nullable object)
    Total discount amount. A positive number reduces the amount to be paid.

    - `amount` (string)
      A formatted string representing the discount amount, including currency symbols.

    - `minorUnitsAmount` (integer)
      An integer representing the discount amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

  - `taxExclusive` (nullable object)
    Total amount of exclusive tax (tax that is collected in addition to the subtotal).

    - `amount` (string)
      A formatted string representing the exclusive tax amount, including currency symbols.

    - `minorUnitsAmount` (integer)
      An integer representing the exclusive tax amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

  - `taxInclusive` (nullable object)
    Total amount of inclusive tax (tax that is already included in the subtotal).

    - `amount` (string)
      A formatted string representing the inclusive tax amount, including currency symbols.

    - `minorUnitsAmount` (integer)
      An integer representing the inclusive tax amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

  - `total` (nullable object)
    Total amount for this line item, including discounts and tax.

    - `amount` (string)
      A formatted string representing the total amount, including currency symbols.

    - `minorUnitsAmount` (integer)
      An integer representing the total amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

  - `unitAmount` (nullable object)
    The amount representing the cost of a single unit of the item.

    - `amount` (string)
      A formatted string representing the unit amount, including currency symbols.

    - `minorUnitsAmount` (integer)
      An integer representing the unit amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

  - `description` (optional string)
    An arbitrary string attached to the object. Often useful for displaying to users.

  - `name` (string)
    The item's name, meant to be displayable to users.

  - `images` (array of strings)
    An array of image URLs for the line item. Specify [images](/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data-product_data-images) on the Product when creating the Checkout Session.

  - `quantity` (integer)
    The quantity of products being purchased.

  - `discountAmounts` (array of objects)
    The amount of discount calculated per discount for this line item.

    - `amount` (string)
      A formatted string representing the discount amount, including currency symbols.

    - `minorUnitsAmount` (integer)
      An integer representing the discount amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    - `displayName` (string)
      A user-facing description of the discount.

    - `promotionCode` (nullable string)
      The customer-facing promotion code that was used to apply this discount, if any.

    - `recurring` (nullable object)
      Details of how the discount applies to recurring payments.

      - `type` (enum)
        One of `forever` or `repeating`.
* `forever`: Applies to all charges from a subscription with this coupon applied.
* `repeating`: Applies to charges in the first `durationInMonths` months from a subscription with this coupon applied.

      - `durationInMonths` (nullable integer)
        If `duration` is `repeating`, the number of months the coupon applies. Null otherwise.

    - `percentOff` (nullable integer)
      An integer representing the discount amount as a percentage.

  - `taxAmounts` (nullable array of objects)
    The amount of tax calculated per tax rate for this line item.

    - `amount` (string)
      A formatted string representing the tax amount, including currency symbols.

    - `minorUnitsAmount` (integer)
      An integer representing the tax amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    - `inclusive` (boolean)
      Whether this tax amount is [inclusive or exclusive](/tax/faq.md#what-is-the-difference-between-inclusive-and-exclusive-tax).

    - `displayName` (string)
      A user-facing description of the tax.

  - `recurring` (nullable object)
    The recurring components of a price such as `interval` and `intervalCount`.

    - `interval` (enum)
      Specifies billing frequency. Either `day`, `week`, `month`, or `year`.

    - `intervalCount` (integer)
      The number of intervals between subscription billings. For
example, `interval=month` and `intervalCount=3` bills
every 3 months.

    - `usageType` (enum)
      One of `licensed` or `metered`. `licensed` automatically
bills the quantity set when adding it to a subscription.
`metered` aggregates the total usage based on usage records.

    - `isProrated` (boolean)
      When true, the amount to be collected today is a prorated
amount for a partial billing period, such as when using
[billing_cycle_anchor](/api/checkout/sessions/create.md#create_checkout_session-subscription_data-billing_cycle_anchor).

  - `adjustableQuantity` (nullable object)
    Configuration for this item's quantity to be adjusted by the
customer during checkout.

    - `maximum` (integer)
      The maximum quantity the customer can purchase for the Checkout Session.

    - `minimum` (integer)
      The minimum quantity the customer can purchase for the Checkout Session.

- `livemode` (boolean)
  Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.

- `minorUnitsAmountDivisor` (integer)
  The factor used to convert between minor and major currency units.

This value represents the number of minor currency units per one major unit. For example, in USD, where cents are the minor unit, the divisor is 100.  In JPY, which has no minor units, the divisor is 1.

- `phoneNumber` (nullable string)
  The Customer's phone number.

- `recurring` (object)
  Details about recurring payments set up by the Checkout Session.

  - `interval` (enum)
    Specifies billing frequency. Either `day`, `week`, `month`, or `year`.

  - `intervalCount` (integer)
    The number of intervals between subscription billings. For
example, `interval=month` and `intervalCount=3` bills every 3
months.

  - `dueNext` (object)
    Details about the next scheduled recurring payment.

    - `subtotal` (nullable object)
      Total before any discounts or exclusive taxes are applied.

      - `amount` (string)
        A formatted string representing the subtotal amount, including currency symbols.

      - `minorUnitsAmount` (integer)
        An integer representing the subtotal amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    - `discount` (nullable object)
      Total discount amount. A positive number reduces the amount to be paid.

      - `amount` (string)
        A formatted string representing the discount amount, including currency symbols.

      - `minorUnitsAmount` (integer)
        An integer representing the discount amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    - `taxExclusive` (nullable object)
      Total amount of exclusive tax (tax that is collected in addition to the subtotal).

      - `amount` (string)
        A formatted string representing the exclusive tax amount, including currency symbols.

      - `minorUnitsAmount` (integer)
        An integer representing the exclusive tax amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    - `taxInclusive` (nullable object)
      Total amount of inclusive tax (tax that is already included in the subtotal).

      - `amount` (string)
        A formatted string representing the inclusive tax amount, including currency symbols.

      - `minorUnitsAmount` (integer)
        An integer representing the inclusive tax amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    - `billingCycleAnchor` (nullable integer)
      A future Unix timestamp to anchor the subscription's billing
cycle. The anchor is the reference point that aligns future
billing cycle dates. If not present, the subscription starts immediately.

  - `trial` (nullable object)
    Details about a free trial, if there is one.

    - `trialEnd` (integer)
      Unix timestamp representing the end of the trial period the
customer will get before being charged for the first time.

    - `trialPeriodDays` (integer)
      Integer representing the number of trial period days before the customer is charged for the first time.

- `savedPaymentMethods` (array of objects)
  An array of payment methods attached to the Customer.

  - `id` (string)
    ID of the PaymentMethod object

  - `type` (enum)
    The [type](/api/payment_methods/object.md#payment_method_object-type) of the PaymentMethod

  - `billingDetails` (object)
    Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods.

    - `email` (nullable string)
      Email address.

    - `phone` (nullable string)
      Billing phone number (including extension).

    - `name` (nullable string)
      Full name.

    - `address` (nullable object)
      Address.

      - `country` (string)
        Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).

      - `line1` (nullable string)
        Address line 1 (e.g., street, PO Box, or company name).

      - `line2` (nullable string)
        Address line 2 (e.g., apartment, suite, unit, or building).

      - `city` (nullable string)
        City, district, suburb, town, or village.

      - `postal_code` (nullable string)
        ZIP or postal code.

      - `state` (nullable string)
        State, county, province, or region.

  - `card` (object)
    If this is a `card` PaymentMethod, this hash contains the user's card details.

    - `brand` (string)
      The brand to use when displaying the card, this accounts for customer's brand choice on dual-branded cards.
Can be american_express, cartes_bancaires, diners_club, discover, eftpos_australia, interac, jcb, mastercard, union_pay, visa,
or other and may contain more values in the future.

    - `expMonth` (integer)
      Two-digit number representing the card's expiration month.

    - `expYear` (integer)
      Four-digit number representing the card's expiration year.

    - `last4` (string)
      The last four digits of the card.

- `shipping` (nullable object)
  The selected shipping option, if any.

  - `shippingOption` (object)
    Details of the selected shipping option.

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

    - `amount` (string)
      A formatted string representing the shipping amount, including currency symbols.

    - `minorUnitsAmount` (integer)
      An integer representing the shipping amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    - `currency` (string)
      Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase.

    - `displayName` (nullable string)
      A user-facing description of the shipping option.

    - `deliveryEstimate` (nullable object)
      The estimated range for how long shipping will take.

      - `maximum` (nullable object)
        The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite.

        - `unit` (string)
          A unit of time. Either `business_day`, `day`, `hour`, `week`, or `month`.

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

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

        - `unit` (string)
          A unit of time. Either `business_day`, `day`, `hour`, `week`, or `month`.

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

  - `taxAmounts` (array of objects)
    The amount of tax calculated per tax rate for shipping costs.

    - `amount` (string)
      A formatted string representing the tax amount, including currency symbols.

    - `minorUnitsAmount` (integer)
      An integer representing the tax amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

    - `inclusive` (boolean)
      Whether this tax amount is [inclusive or exclusive](/tax/faq.md#what-is-the-difference-between-inclusive-and-exclusive-tax).

    - `displayName` (string)
      A user-facing description of the tax.

- `shippingAddress` (nullable object)
  Shipping address of the Customer.

  - `name` (nullable string)
    Full name.

  - `address` (nullable object)
    Address.

    - `country` (string)
      Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).

    - `line1` (string)
      Address line 1 (e.g., street, PO Box, or company name).

    - `line2` (nullable string)
      Address line 2 (e.g., apartment, suite, unit, or building).

    - `city` (nullable string)
      City, district, suburb, town, or village.

    - `postal_code` (nullable string)
      ZIP or postal code.

    - `state` (nullable string)
      State, county, province, or region.

- `shippingOptions` (array of objects)
  The list of shipping options that can be selected.

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

  - `amount` (string)
    A formatted string representing the shipping amount, including currency symbols.

  - `minorUnitsAmount` (integer)
    An integer representing the shipping amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

  - `currency` (string)
    Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase.

  - `displayName` (nullable string)
    A user-facing description of the shipping option.

  - `deliveryEstimate` (nullable object)
    The estimated range for how long shipping will take.

    - `maximum` (nullable object)
      The upper bound of the estimated range. If empty, represents no upper bound i.e., infinite.

      - `unit` (string)
        A unit of time. Either `business_day`, `day`, `hour`, `week`, or `month`.

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

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

      - `unit` (string)
        A unit of time. Either `business_day`, `day`, `hour`, `week`, or `month`.

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

- `status` (object)
  Status of the Checkout Session.

  - `type` (enum)
    One of `open`, `expired`, or `complete`.
* `open`: The Checkout Session is still in progress.
* `expired`: The Checkout Session has expired. No further processing will occur.
* `complete`: The Checkout Session is complete. Payment processing may still be in progress.

  - `paymentStatus` (nullable enum)
    One of `paid`, `unpaid`, or `no_payment_required`. Only present when `type=complete`.
* `paid`: The payment funds are available in your account.
* `unpaid`: The payment funds are not yet available in your account.
* `no_payment_required`: The payment is delayed to a future date, or the Checkout Session is in setup mode and doesn't require a payment at this time.

- `tax` (object)
  Details about the tax computation status.

  - `status` (enum)
    One of `ready`, `requires_shipping_address`, or `requires_billing_address`.
* `ready`: The final tax amount is computed, and the session is ready for confirmation.
* `requires_shipping_address`: A shipping address must be provided to calculate tax.
* `requires_billing_address`: A billing address must be provided to calculate tax.

- `taxAmounts` (nullable array of objects)
  The aggregate amounts calculated per tax rate for all line
items. This value is `null` if tax has not yet been computed,
i.e. the Customer's address has not been collected yet.

  - `amount` (string)
    A formatted string representing the tax amount, including currency symbols.

  - `minorUnitsAmount` (integer)
    An integer representing the tax amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

  - `inclusive` (boolean)
    Whether this tax amount is [inclusive or exclusive](/tax/faq.md#what-is-the-difference-between-inclusive-and-exclusive-tax).

  - `displayName` (string)
    A user-facing description of the tax.

- `total` (object)
  Tax and discount details for the computed total amount. Use this
field to render an amount breakdown to your customer, such as in an
order summary.

  - `subtotal` (object)
    The total amount of line items, excluding tax, discounts, and shipping.

    - `amount` (string)
      A formatted string representing the subtotal amount, including currency symbols.

    - `minorUnitsAmount` (integer)
      An integer representing the subtotal amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

  - `taxExclusive` (object)
    The sum of all [exclusive](/tax/faq.md#what-is-the-difference-between-inclusive-and-exclusive-tax) tax amounts

    - `amount` (string)
      A formatted string representing the exclusive tax amount, including currency symbols.

    - `minorUnitsAmount` (integer)
      An integer representing the exclusive tax amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

  - `taxInclusive` (object)
    The sum of all [inclusive](/tax/faq.md#what-is-the-difference-between-inclusive-and-exclusive-tax) tax amounts

    - `amount` (string)
      A formatted string representing the inclusive tax amount, including currency symbols.

    - `minorUnitsAmount` (integer)
      An integer representing the inclusive tax amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

  - `shippingRate` (object)
    The sum of all shipping amounts.

    - `amount` (string)
      A formatted string representing the total shipping amount, including currency symbols.

    - `minorUnitsAmount` (integer)
      An integer representing the total shipping amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

  - `discount` (object)
    The sum of all the discounts. A positive number reduces the amount to be paid.

    - `amount` (string)
      A formatted string representing the discount amount, including currency symbols.

    - `minorUnitsAmount` (integer)
      An integer representing the discount amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

  - `total` (object)
    Total computed amount, including discounts and tax.

    - `amount` (string)
      A formatted string representing the total amount, including currency symbols.

    - `minorUnitsAmount` (integer)
      An integer representing the total amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

  - `appliedBalance` (object)
    Total amount of [customer credit balance](/billing/customer/balance.md) to be applied to the payment. A positive number increases the amount to be paid, and a negative number decreases the amount to be paid.

    - `amount` (string)
      A formatted string representing the applied customer balance amount, including currency symbols.

    - `minorUnitsAmount` (integer)
      An integer representing the applied customer balance amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

  - `balanceAppliedToNextInvoice` (boolean)
    When true, no payment will be collected immediately. Instead, the amount due will be added to the Customer's next invoice. This can happen when the amount due today is less than the [minimum chargeable amount](/currencies.md#minimum-and-maximum-charge-amounts).

## PricingPlanSubscriptionItem

Contains information about the Pricing Plan Subscription that the customer is signing up for.

- `type` (enum)
  Always equal to `pricing_plan_subscription_item`.

- `displayName` (string)
  The display name of the Pricing Plan.

- `images` (array of strings)
  An array of image URLs for the Pricing Plan.

- `components` (array of objects)
  The Pricing Plan's components. Each item is either a [LicenseFeeSubscriptionItem](#license_fee_subscription_item) or a [RateCardSubscriptionItem](#rate_card_subscription_item).

## LicenseFeeSubscriptionItem

A License Fee component of a Pricing Plan Subscription that defines per-unit pricing.

- `type` (enum)
  Always equal to `license_fee_subscription_item`.

- `displayName` (string)
  The display name.

- `unitLabel` (nullable string)
  The label for the unit being priced.

- `servicing` (object)
  Details about the servicing interval for this License Fee.

  - `interval` (enum)
    Specifies servicing frequency. Either `day`, `week`, `month`, or `year`.

  - `intervalCount` (integer)
    The number of intervals between assessing service. For
example, `interval=month` and `intervalCount=3` assesses service every 3
months.

- `total` (object)
  The total amount including all taxes and fees for this License Fee.

  - `amount` (string)
    A formatted string representing the total amount, including currency symbols.

  - `minorUnitsAmount` (integer)
    An integer representing the total amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

- `subtotal` (object)
  The subtotal amount before taxes are applied to this License Fee.

  - `amount` (string)
    A formatted string representing the subtotal amount, including currency symbols.

  - `minorUnitsAmount` (integer)
    An integer representing the subtotal amount in the [smallest currency unit](/currencies.md#zero-decimal).

- `taxAmounts` (array of objects)
  An array of tax amounts applied to this License Fee.

  - `inclusive` (boolean)
    Whether this tax amount is inclusive or exclusive.

  - `displayName` (string)
    The display name for this tax.

  - `amount` (string)
    A formatted string representing the tax amount, including currency symbols.

  - `minorUnitsAmount` (integer)
    An integer representing the tax amount in the [smallest currency unit](/currencies.md#zero-decimal).

- `taxInclusive` (object)
  The total amount of inclusive tax applied.

  - `amount` (string)
    A formatted string representing the amount of inclusive tax, including currency symbols.

  - `minorUnitsAmount` (integer)
    An integer representing the amount of inclusive tax in the [smallest currency unit](/currencies.md#zero-decimal).

- `taxExclusive` (object)
  The total amount of exclusive tax applied.

  - `amount` (string)
    A formatted string representing the amount of exclusive tax, including currency symbols.

  - `minorUnitsAmount` (integer)
    An integer representing the amount of exclusive tax in the [smallest currency unit](/currencies.md#zero-decimal).

- `quantity` (number)
  The quantity of licenses or units being purchased.

- `unitAmount` (nullable object)
  The per-unit amount. Exclusive with `tiering`.

  - `amount` (string)
    A formatted string representing the unit amount, including currency symbols.

  - `minorUnitsAmount` (integer)
    An integer representing the unit amount in the [smallest currency unit](/currencies.md#zero-decimal).

- `tiering` (nullable object)
  Tiered pricing structure. Exclusive with `unitAmount`.

  - `mode` (enum)
    The tiering mode. Either `graduated` or `volume`.

  - `tiers` (array of objects)
    An array of pricing tiers.

    - `flatAmount` (object)
      The flat amount for this tier.

      - `amount` (string)
        A formatted string representing the amount, including currency symbols.

      - `minorUnitsAmount` (number)
        An integer representing the amount in the [smallest currency unit](/currencies.md#zero-decimal).

    - `unitAmount` (object)
      The per-unit amount for this tier.

      - `amount` (string)
        A formatted string representing the amount, including currency symbols.

      - `minorUnitsAmount` (number)
        An integer representing the amount in the [smallest currency unit](/currencies.md#zero-decimal).

    - `upTo` (nullable number)
      The upper bound for this tier. `null` means infinity.

- `packageSize` (nullable number)
  Package pricing size. Exclusive with `tiering`. For example, `packageSize=10` means the price is per 10 units.

## RateCardSubscriptionItem

A Rate Card component of a Pricing Plan Subscription that describes usage-based pricing.

- `type` (enum)
  Always equal to `rate_card_subscription_item`.

- `displayName` (string)
  The display name of the Rate Card.

- `servicing` (object)
  The interval for assessing service for this Rate Card.

  - `interval` (enum)
    Specifies servicing frequency. Either `day`, `week`, `month`, or `year`.

  - `intervalCount` (integer)
    The number of intervals between assessing service. For
example, `interval=month` and `intervalCount=3` assesses service every 3
months.

- `rates` (array of objects)
  An array of rates that define the pricing structure. Limited to first 50 rates.

  - `displayName` (string)
    The display name for the rate.

  - `unitLabel` (string)
    The label for the unit being priced (e.g., "API call", "GB stored").

  - `unitAmount` (nullable object)
    The per-unit amount for the rate. Exclusive with `tiering`.

    - `amount` (string)
      A formatted string representing the amount, including currency symbols.

    - `minorUnitsAmount` (number)
      An integer representing the amount in the [smallest currency unit](/currencies.md#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

  - `tiering` (nullable object)
    Tiered pricing structure for this rate. Exclusive with `unitAmount`.

    - `mode` (enum)
      The tiering mode. Either `graduated` or `volume`.

    - `tiers` (array of objects)
      An array of pricing tiers.

      - `flatAmount` (object)
        The flat amount for this tier.

        - `amount` (string)
          A formatted string representing the amount, including currency symbols.

        - `minorUnitsAmount` (number)
          An integer representing the amount in the [smallest currency unit](/currencies.md#zero-decimal).

      - `unitAmount` (object)
        The per-unit amount for this tier.

        - `amount` (string)
          A formatted string representing the amount, including currency symbols.

        - `minorUnitsAmount` (number)
          An integer representing the amount in the [smallest currency unit](/currencies.md#zero-decimal).

      - `upTo` (nullable number)
        The upper bound for this tier. `null` means infinity.

  - `packageSize` (nullable number)
    Package pricing size for this rate. Exclusive with `tiering`.

## Checkout events

Listen to Checkout events to respond to changes caused by customer actions on your checkout page.

## Change event

The change event is triggered when [Checkout Session](/js/custom_checkout/session_object.md)
data changes, such as when the customer changes their shipping
address.  The event payload is always a [Checkout Session](/js/custom_checkout/session_object.md)
object.

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

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

- `handler` (function) **required**
  `handler(session) => void` is a **callback function** that
you provide that will be called when the event is fired. When called
it will be passed a [Checkout Session](/js/custom_checkout/session_object.md) object.

### Listen to change events

```js
checkout.on('change', function(session) {
  // Read new data
});
```

```es_next
checkout.on('change', (session) => {
  // Read new data
});
```

## Use Elements with the Checkout Sessions API

[Stripe Elements](/payments/elements.md) are customizable UI
components you can use to build your checkout page.

Use the [Checkout](/js/custom_checkout.md)
instance to create and manage Elements.

## Create a Payment Form Element

This method creates an instance of a Payment Form Element.

This method returns the newly created Payment Form Element instance.

**Syntax:** `checkout.createPaymentFormElement(...)`

- `options` (object)
  Payment Form Element initialization options.

  - `layout` ('expanded' | 'compact')
    The layout of the Payment Form Element. The `'expanded'` layout is a single-step checkout form, while the `'compact'` layout is a multi-step checkout form. When you leave this undefined, Stripe renders the layout it determines has the best conversion.

  - `contacts` (array)
    An array of [Contact](/js/appendix/contact_object.md) objects that you can use to display saved addresses in the Payment Form Element. The first contact is automatically selected.

  - `expressCheckout` (object)
    Express checkout configuration options.

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

    - `paymentMethods` (object)
      Besides your Dashboard configuration, the availability of payment methods in the Payment Form Element is influenced by the CheckoutSession configuration. By default, it displays all available payment methods based on both configurations. When setting the paymentMethods option, the Payment Form Element merges your specified options with the default logic to determine the final set of payment methods displayed.

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

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

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

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

### Create a Payment Form Element

```js
var element = checkout.createPaymentFormElement();
```

```es_next
const element = checkout.createPaymentFormElement();
```

## Create a Payment Element

This method creates an instance of a Payment Element.

This method returns the newly created Payment Element instance.

**Syntax:** `checkout.createPaymentElement(...)`

- `options` (object)
  Payment Element initialization options.

  - `fields` (object)
    By default, the Payment Element will collect only the necessary billing details to complete a payment.

If you intend to collect billing details fields outside of the Payment Element, you can disable Payment Element collection of certain fields with the `fields` option.

    - `billingDetails` ('never' | 'auto' | object)
      Specify `never` to avoid collecting all [billing details](/api/payment_methods/object.md#payment_method_object-billing_details)
in the Payment Element. If you would like to disable only certain billing details,
pass an object specifying which fields you would like to disable collection for.
The default setting for each field or object is `auto`.

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

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

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

      - `address` ('never' | 'if_required' | 'auto' | object)
        Specify `if_required` to only collect the minimum billing address fields required to complete the payment.
You can omit and hide optional address fields in the card form, such as country and postal code.
Unlike the `never` option, you don't need to include fields omitted in the Payment Element when confirming the payment.
This can reduce the amount of information required to complete the form.

Disabling address collection can negatively impact authorization rates and network fees for users on a network cost plus pricing plan.

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

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

        - `city` ('never' | 'auto')
          The name of a city, town, village, etc.

        - `state` ('never' | 'auto')
          The most coarse subdivision of a country.
Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines.

        - `country` ('never' | 'auto')
          Two-letter country code, capitalized. Valid two-letter country codes are specified by ISO3166 alpha-2.

        - `postalCode` ('never' | 'auto')
          The postal code or ZIP code, also known as PIN code in India.

  - `layout` ('accordion' | 'tabs' | object)
    Specify the layout for the Payment Element. If you only pass a layout type (`'accordion'` or `‘tabs’`) without any additional parameters, the Payment Element renders using that layout and the default values associated with it.

An object can also be passed to specify the layout with additional configuration.

    - `type` ('accordion' | 'tabs') **required**
      Defines the layout to render the Payment Element.

    - `defaultCollapsed` (boolean)
      Controls if the Payment Element renders in a collapsed state (where no payment method is selected by default). When you leave this `undefined`, Stripe renders the experience that it determines will have the best conversion.

    - `radios` ('always' | 'never' | 'if_multiple' | 'auto')
      Controls when to render each Payment Method with a radio input next to its logo. The radios visually indicate the current selection of the Payment Element. Defaults to `'auto'`.

- `'always'` — Always show radio inputs.
- `'never'` — Never show radio inputs.
- `'if_multiple'` — Show radio inputs only when there are multiple payment methods available. When there is only one payment method, no radio input is displayed.
- `'auto'` — Stripe determines the best experience to optimize conversion.

_This property is only applicable to the `accordion` layout._

    - `spacedAccordionItems` (boolean)
      When `true`, the Payment Methods render as standalone buttons with space in between them.

_This property is only applicable to the `accordion` layout._

    - `visibleAccordionItemsCount` (number)
      Sets the max number of Payment Methods visible before using the "More" button to hide additional Payment Methods. Set this value to `0` to disable the "More" button and render all available Payment Methods. Default is `5`.

_This property is only applicable to the `accordion` layout._

    - `paymentMethodLogoPosition` ('start' | 'end')
      Sets the position of the payment method logo in each accordion item. Default is `start`.

_This property is only applicable to the `accordion` layout._

  - `paymentMethodOrder` (array)
    By default, the Payment Element will use a dynamic ordering that optimizes payment method display for each user.

You can override the default order in which payment methods are displayed in the Payment Element with a list of payment method types.

If the associated Checkout Session has payment method types not specified in `paymentMethodOrder`, they will be displayed
after the payment methods you specify. If you specify payment method types not on the associated PaymentIntent, they will be ignored.

  - `readOnly` (boolean)
    Applies a read-only state to the Payment Element so that payment details can’t be changed. Default is false.

Enabling the `readOnly` option doesn't change the Payment Element's visual appearance. If you want to adjust the way the Payment Element looks, use the [Appearance API](/elements/appearance-api.md).

  - `terms` (object)
    Control how mandates or other legal agreements are displayed in the Payment Element.
Use `never` to never display legal agreements. The default setting is `auto`, which causes
legal agreements to only be shown when necessary.

Consult your legal and compliance advisors before making any changes to the text of mandates or legal agreements. You can't use the `terms` option to violate obligations under your Stripe agreement, Stripe policies, applicable laws or scheme rules.

    - `applePay` ('auto' | 'always' | 'never')

    - `auBecsDebit` ('auto' | 'always' | 'never')

    - `bancontact` ('auto' | 'always' | 'never')

    - `card` ('auto' | 'always' | 'never')

    - `cashapp` ('auto' | 'always' | 'never')

    - `googlePay` ('auto' | 'always' | 'never')

    - `ideal` ('auto' | 'always' | 'never')

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

    - `sepaDebit` ('auto' | 'always' | 'never')

    - `sofort` ('auto' | 'always' | 'never')

    - `usBankAccount` ('auto' | 'always' | 'never')

  - `wallets` (object)
    By default, the Payment Element will display all the payment
methods that the underlying Checkout Session was created with.

However, wallets like Apple Pay and Google Pay are not payment
methods per the Checkout Session API. They will show when the
Checkout Session has the `card` payment method and the customer is
using a supported platform and have an active card in their
account.  This is the `auto` behavior, and it is the default for
choice for all wallets.

If you do not want to show a given wallet as a payment option, you
can set its property in `wallets` to `never`.

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

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

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

### Create a Payment Element

```js
var element = checkout.createPaymentElement();
```

```es_next
const element = checkout.createPaymentElement();
```

## Create a Billing Address Element

This method creates an instance of a Billing Address Element.

This method returns the newly created Billing Address Element instance.

**Syntax:** `checkout.createBillingAddressElement(...)`

- `options` (object)
  Billing Address Element initialization options.

  - `contacts` (array)
    An array of [Contact](/js/appendix/contact_object.md) objects that can be displayed as saved addresses in the Billing Address Element. The first contact is automatically selected.

  - `display` (object)
    You can customize how certain fields are displayed.

    - `name` ('full' | 'split' | 'organization')
      By default, the Billing Address Element displays a full name field.
Specify 'split' to display a first name field and a last name field.
Specify 'organization' to display an organization field.

### Create a Billing Address Element

```js
var element = checkout.createBillingAddressElement();
```

```es_next
const element = checkout.createBillingAddressElement();
```

## Create a Shipping Address Element

This method creates an instance of a Shipping Address Element.

This method returns the newly created Shipping Address Element instance.

**Syntax:** `checkout.createShippingAddressElement(...)`

- `options` (object)
  Shipping Address Element initialization options.

  - `contacts` (array)
    An array of [Contact](/js/appendix/contact_object.md) objects that can be displayed as saved addresses in the Shipping Address Element. The first contact is automatically selected.

  - `display` (object)
    You can customize how certain fields are displayed.

    - `name` ('full' | 'split' | 'organization')
      By default, the Shipping Address Element displays a full name field.
Specify 'split' to display a first name field and a last name field.
Specify 'organization' to display an organization field.

### Create a Shipping Address Element

```js
var element = checkout.createShippingAddressElement();
```

```es_next
const element = checkout.createShippingAddressElement();
```

## Create an Express Checkout Element

This method creates an instance of an Express Checkout Element.

This method returns the newly created Express Checkout Element instance.

**Syntax:** `checkout.createExpressCheckoutElement(...)`

- `options` (object)
  Express Checkout Element initialization options.

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

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

  - `paymentMethods` (object)
    Besides your Dashboard configuration, the availability of payment methods in the Express Checkout Element is influenced by the CheckoutSession configuration. By default, it displays all available payment methods based on both configurations. When setting the paymentMethods option, the Express Checkout Element merges your specified options with the default logic to determine the final set of payment methods displayed.

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

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

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

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

### Create an Express Checkout Element

```js
var element = checkout.createExpressCheckoutElement();
```

```es_next
const element = checkout.createExpressCheckoutElement();
```

## Create a Currency Selector Element

This method creates an instance of a Currency Selector Element.

This method returns the newly created Currency Selector Element instance.

**Syntax:** `checkout.createCurrencySelectorElement(...)`

### Create a Currency Selector Element

```js
var element = checkout.createCurrencySelectorElement();
```

```es_next
const element = checkout.createCurrencySelectorElement();
```

## Create a Tax ID Element

This method creates an instance of a Tax ID Element.

> This feature requires the `custom_checkout_tax_id_1` beta. To use it, pass `betas: ['custom_checkout_tax_id_1']` when initializing Stripe.js.

This method returns the newly created Tax ID Element instance.

**Syntax:** `checkout.createTaxIdElement(...)`

- `options` (object)
  Tax ID Element initialization options.

  - `visibility` ('always' | 'never' | 'auto')
    By default, the Tax ID Element displays when the user is in a country that supports tax ID collection.
Specify `always` to display the element regardless of the user's country.
Specify `never` to hide the element completely.

  - `fields` (object)
    By default, the Tax ID Element collects all tax ID information.

If it's not necessary for you to collect all fields, you can disable Tax ID Element collection of certain fields with the `fields` option.

    - `businessName` ('always' | 'never' | 'auto')
      Specify `always` to collect the business name.
Specify `never` to not collect the business name.
Default is `auto`.

  - `validation` (object)
    By default, the Tax ID Element will enforce preset validation for each field. You can customize the settings by using this option.

    - `businessName` (object)

      - `required` ('always' | 'never' | 'auto')
        Specify `always` to make business name a required field.
Specify `never` to make business name an optional field.
Default is `auto`.

    - `taxId` (object)

      - `required` ('always' | 'never' | 'auto')
        Specify `always` to make tax ID a required field.
Specify `never` to make tax ID an optional field.
Default is `auto`.

### Create a Tax ID Element

```js
var element = checkout.createTaxIdElement();
```

```es_next
const element = checkout.createTaxIdElement();
```

## Get the Payment Form Element

This method gets the previously created Payment Form Element instance, if it exists.

`getPaymentFormElement()` returns one of the following:
* The Payment Form Element instance.
* `null`, when no Payment Form Element has been created.

**Syntax:** `checkout.getPaymentFormElement(...)`

### Get the Payment Form Element

```js
var element = checkout.getPaymentFormElement();
```

```es_next
const element = checkout.getPaymentFormElement();
```

## Set the view on the Payment Form Element

Programmatically sets the active view on the Payment Form Element. This method is only available when `options[layout]` is `'compact'`.

The `viewIndex` parameter is a positive integer that corresponds to an index from the `views` array provided on the Element's [change event](/js/custom_checkout/element_events/on_change.md?type=paymentFormElement). You can only set a view where `enabled` is `true`.

`setView` returns a `Promise` that resolves when the view has been set. The `Promise` rejects with an `IntegrationError` if:
* The `viewIndex` is not a positive integer.
* The `viewIndex` exceeds the total views length provided on the Element's change event.
* The view at the specified index has `enabled: false`.
* The Element's `options[layout]` is `'expanded'`.

**Syntax:** `paymentFormElement.setView(...)`

- `viewIndex` (number) **required**
  A positive integer index corresponding to an entry in the `views` array provided on the Element's [change event](/js/custom_checkout/element_events/on_change.md?type=paymentFormElement). The view at the specified index must have `enabled: true`.

### Set the view on the Payment Form Element

```js
var paymentFormElement = checkout.createPaymentFormElement({ layout: 'compact' });
paymentFormElement.setView(1);
```

```es_next
const paymentFormElement = checkout.createPaymentFormElement({ layout: 'compact' });
paymentFormElement.setView(1);
```

## Get the Payment Element

This method gets the previously created Payment Element instance, if it exists.

`getPaymentElement()` returns one of the following:
* The Payment Element instance.
* `null`, when no Payment Element has been created.

**Syntax:** `checkout.getPaymentElement(...)`

### Get the Payment Element

```js
var element = checkout.getPaymentElement();
```

```es_next
const element = checkout.getPaymentElement();
```

## Get the Billing Address Element

This method gets the previously created Billing Address Element instance, if it exists.

`getBillingAddressElement()` returns one of the following:
* The Billing Address Element instance.
* `null`, when no Billing Address Element has been created.

**Syntax:** `checkout.getBillingAddressElement(...)`

### Get the Billing Address Element

```js
var element = checkout.getBillingAddressElement();
```

```es_next
const element = checkout.getBillingAddressElement();
```

## Get the Shipping Address Element

This method gets the previously created Shipping Address Element instance, if it exists.

`getShippingAddressElement()` returns one of the following:
* The Shipping Address Element instance.
* `null`, when no Shipping Address Element has been created.

**Syntax:** `checkout.getShippingAddressElement(...)`

### Get the Shipping Address Element

```js
var element = checkout.getShippingAddressElement();
```

```es_next
const element = checkout.getShippingAddressElement();
```

## Get the Express Checkout Element

This method gets the previously created Express Checkout Element instance, if it exists.

`getExpressCheckoutElement()` returns one of the following:
* The Express Checkout Element instance.
* `null`, when no Express Checkout Element has been created.

**Syntax:** `checkout.getExpressCheckoutElement(...)`

### Get the Express Checkout Address Element

```js
var element = checkout.getExpressCheckoutElement();
```

```es_next
const element = checkout.getExpressCheckoutElement();
```

## Get the Currency Selector Element

This method gets the previously created Currency Selector Element instance, if it exists.

`getCurrencySelectorElement()` returns one of the following:
* The Currency Selector Element instance.
* `null`, when no Currency Selector Element has been created.

**Syntax:** `checkout.getCurrencySelectorElement(...)`

### Get the Currency Selector Address Element

```js
var element = checkout.getCurrencySelectorElement();
```

```es_next
const element = checkout.getCurrencySelectorElement();
```

## Get the Tax ID Element

This method gets the previously created Tax ID Element instance, if it exists.

`getTaxIdElement()` returns one of the following:
* The Tax ID Element instance.
* `null`, when no Tax ID Element has been created.

**Syntax:** `checkout.getTaxIdElement(...)`

### Get the Tax ID Element

```js
var element = checkout.getTaxIdElement();
```

```es_next
const element = checkout.getTaxIdElement();
```

## Change the visual customization of Elements using the Appearance API

Change the visual customization of Elements created with Custom
Checkout using the [Appearance API](/elements/appearance-api.md)

**Syntax:** `checkout.changeAppearance(...)`

- `appearance` (object) **required**
  Match the design of your site with the [appearance option](/elements/appearance-api.md).
The layout of each Element stays consistent, but you can modify colors, fonts, borders, padding, and more.

### Change the visual customization of Elements

```js
checkout.changeAppearance({
  theme: 'night',
  labels: 'floating',
});
```

```es_next
checkout.changeAppearance({
  theme: 'night',
  labels: 'floating',
});
```

## Load additional custom fonts into Elements

Load an additional array of custom fonts into Elements after it loads.

**Syntax:** `checkout.loadFonts(...)`

- `fonts` (array) **required**
  An array of custom fonts.

Specify fonts as [CssFontSource](#css_font_source_object)
or [CustomFontSource](#custom_font_source_object) objects.

### Load additional custom fonts

```js
checkout.loadFonts([
  {
    cssSrc: "https://fonts.googleapis.com/css?family=Open+Sans",
  },
]);
```

```es_next
checkout.loadFonts([
  {
    cssSrc: "https://fonts.googleapis.com/css?family=Open+Sans",
  },
]);
```

## Listen to Elements events

Communicate with your [Element](/js/custom_checkout/custom_checkout_elements.md) by listening to an event.
An Element might emit any of the events below.
All events have a payload object that has an `elementType` property with the type of the `Element` that emitted the event.

Use the `.on` method on the Element instance to listen to events.

See also: [Elements methods](/js/custom_checkout/custom_checkout_elements.md) | [Listen to Checkout events](/js/custom_checkout/events.md)

## Change event

The change event is triggered when any value in the change event payload changes.
The event payload always contains certain keys, in addition to some `Element`-specific keys.

The following Checkout Elements support the `change` event:
`paymentElement`, `billingAddressElement`, `shippingAddressElement`, and `taxIdElement`.

> Consult with your legal counsel regarding your requirements and obligations about how you collect, use, and store customers' personal data

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

#### paymentElement

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

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that
you provide that will be called when the event is fired. When called
it will pass an event object with the following properties:

  - `elementType` (string)
    The type of element that emitted this event.

  - `empty` (boolean)
    `true` if the value is empty.

  - `complete` (boolean)
    `true` if all required fields for the selected payment method in the Payment Element
have been filled with potentially valid input.

  - `collapsed` (boolean)
    `true` if the Payment Element is currently collapsed.

  - `value` (object)
    An object containing the current selected PaymentMethod type.

    - `type` (string)
      The type of payment method that was selected.

### Handle a payment element change event

```js
const paymentElement = checkout.createPaymentElement();
paymentElement.on('change', function(event) {
  if (event.complete) {
    // enable payment button
  }
});
```

```es_next
const paymentElement = checkout.createPaymentElement();
paymentElement.on('change', (event) => {
  if (event.complete) {
    // enable payment button
  }
});
```

#### billingAddressElement

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

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that
you provide that will be called when the event is fired. When called
it will pass an event object with the following properties:

  - `elementType` (string)
    The type of element that emitted this event.

  - `empty` (boolean)
    `true` if the value is empty.

  - `complete` (boolean)
    `true` if the value is well-formed and potentially complete.
The `complete` value can be used to progressively disclose the next parts of your form or to enable form submission.

It is not an indicator of whether a customer is done with their input—it only indicates that the Element contains a potentially complete, well-formed value.
In many cases the customer could still add further input.

The `complete` value should not be used to perform an action such as advancing the cursor to a subsequent field or performing a tokenization request.

  - `isNewAddress` (boolean)
    `true` if the Billing Address Element is currently displaying the form collection view.

  - `value` (object)
    An object containing the current address information.

### Handle a billing address element change event

```js
const billingAddressElement = checkout.createBillingAddressElement();
billingAddressElement.on('change', function(event) {
  if (event.complete) {
    // extract potentially complete address
  }
});
```

```es_next
const billingAddressElement = checkout.createBillingAddressElement();
billingAddressElement.on('change', (event) => {
  if (event.complete) {
    // extract potentially complete address
  }
});
```

#### shippingAddressElement

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

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that
you provide that will be called when the event is fired. When called
it will pass an event object with the following properties:

  - `elementType` (string)
    The type of element that emitted this event.

  - `empty` (boolean)
    `true` if the value is empty.

  - `complete` (boolean)
    `true` if the value is well-formed and potentially complete.
The `complete` value can be used to progressively disclose the next parts of your form or to enable form submission.

It is not an indicator of whether a customer is done with their input—it only indicates that the Element contains a potentially complete, well-formed value.
In many cases the customer could still add further input.

The `complete` value should not be used to perform an action such as advancing the cursor to a subsequent field or performing a tokenization request.

  - `isNewAddress` (boolean)
    `true` if the Shipping Address Element is currently displaying the form collection view.

  - `value` (object)
    An object containing the current address information.

### Handle a shipping address element change event

```js
const shippingAddressElement = checkout.createShippingAddressElement();
shippingAddressElement.on('change', function(event) {
  if (event.complete) {
    // extract potentially complete address
  }
});
```

```es_next
const shippingAddressElement = checkout.createShippingAddressElement();
shippingAddressElement.on('change', (event) => {
  if (event.complete) {
    // extract potentially complete address
  }
});
```

#### taxIdElement

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

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that
you provide that will be called when the event is fired. When called
it will pass an event object with the following properties:

  - `elementType` (string)
    The type of element that emitted this event.

  - `empty` (boolean)
    `true` if both the business name and tax ID fields are empty.

  - `complete` (boolean)
    `true` if all required fields in the Tax ID Element have been filled with potentially valid input.

  - `visible` (boolean)
    `true` if the Tax ID Element is visible based on the `visibility` option and country.

  - `value` (object)
    An object containing the current tax ID information.

The `taxIdType` value corresponds to the selected country-specific type in the Tax ID Element.
The `externalTaxIdType` value corresponds to the tax ID type you would pass to Stripe APIs (for example, EU countries use `eu_vat`).

    - `businessName` (string)
      The business name entered in the Tax ID Element.

    - `taxId` (string)
      The tax ID value entered in the Tax ID Element.

    - `taxIdType` (string)
      The selected tax ID type in the Tax ID Element (for example, `de_vat`).

    - `externalTaxIdType` (string)
      The tax ID type that corresponds to Stripe API values (for example, `eu_vat`).

### Handle a tax ID element change event

```js
const taxIdElement = checkout.createTaxIdElement();
taxIdElement.on('change', function(event) {
  if (event.complete) {
    // Read tax ID details from event.value
  }
});
```

```es_next
const taxIdElement = checkout.createTaxIdElement();
taxIdElement.on('change', (event) => {
  if (event.complete) {
    // Read tax ID details from event.value
  }
});
```

## Ready event

Triggered when the `Element` is fully rendered and methods on the instance, like `element.focus()` and `element.update()`, can be called.

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

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

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that you provide that will be called when the event is fired.

After it's called, it passes an event object with the following properties:

  - `elementType` (string) **required**
    The type of element the event is fired from.

### Handle an Element ready event

```js
const paymentElement = checkout.createPaymentElement();
paymentElement.on('ready', function(event) {
  // Handle ready event
});
```

```es_next
const paymentElement = checkout.createPaymentElement();
paymentElement.on('ready', (event) => {
  // Handle ready event
});
```

## Focus event

Triggered when the `Element` gains focus.

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

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

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that you provide that will be called when the event is fired.

### Handle an Element focus event

```js
const paymentElement = checkout.createPaymentElement();
paymentElement.on('focus', function(event) {
  // Handle focus event
});
```

```es_next
const paymentElement = checkout.createPaymentElement();
paymentElement.on('focus', (event) => {
  // Handle focus event
});
```

## Blur event

Triggered when the `Element` loses focus.

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

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

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that you provide that will be called when the event is fired.

### Handle an Element blur event

```js
const paymentElement = checkout.createPaymentElement();
paymentElement.on('blur', function(event) {
  // Handle blur event
});
```

```es_next
const paymentElement = checkout.createPaymentElement();
paymentElement.on('blur', (event) => {
  // Handle blur event
});
```

## Escape event

Triggered when the escape key is pressed within an `Element`.

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

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

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that you provide that will be called when the event is fired.

### Handle an Element escape event

```js
const paymentElement = checkout.createPaymentElement();
paymentElement.on('escape', function(event) {
  // Handle escape event
});
```

```es_next
const paymentElement = checkout.createPaymentElement();
paymentElement.on('escape', (event) => {
  // Handle escape event
});
```

## LoadError event

Triggered when the `Element` fails to load.

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

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

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that you provide that will be called when the event is fired.

When called it will be passed an event object with the following properties:

  - `elementType` (string)
    The type of element that emitted this event.

  - `error` (object)
    An `error` object that describes the failure.

### Handle an Element loaderror event

```js
const paymentElement = checkout.createPaymentElement();
paymentElement.on('loaderror', function(event) {
  // Handle loaderror event
});
```

```es_next
const paymentElement = checkout.createPaymentElement();
paymentElement.on('loaderror', (event) => {
  // Handle loaderror event
});
```

## LoaderStart event

Triggered when the loader UI is mounted to the DOM and ready to be displayed.

See also: [Elements methods](/js/custom_checkout/custom_checkout_elements.md) | [Listen to Elements events](/js/custom_checkout/element_events.md)

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

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

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that you provide that will be called when the event is fired.

When called it will be passed an event object with the following properties:

  - `elementType` (string)
    The type of element that emitted this event.

### Handle a Checkout Element loaderstart event

```js
const paymentElement = checkout.createPaymentElement();
paymentElement.on('loaderstart', function(event) {
  // Handle loaderstart event
});
```

```es_next
const paymentElement = checkout.createPaymentElement();
paymentElement.on('loaderstart', (event) => {
  // Handle loaderstart event
});
```

## Confirm event

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

This event is only available on the Express Checkout Element.

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

  - `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` (object)
      The billing address of the customer.

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

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

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

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

### Handle 'confirm' event

```js
const expressCheckoutElement = checkout.createExpressCheckoutElement();
expressCheckoutElement.on('confirm', function(event) {
  // call actions.confirm() to confirm the payment
  actions.confirm().then(function(result) {
    if (result.type === 'error') {
      // Inform the customer that there's an error.
    }
  });
});
```

```es_next
const expressCheckoutElement = checkout.createExpressCheckoutElement();
expressCheckoutElement.on('confirm', async (event) => {
  // call actions.confirm() to confirm the payment
  const result = await actions.confirm();
  if (result.type === 'error') {
    // Inform the customer that there's an error.
  }
});
```

## Cancel event

The `cancel` event is triggered from the 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.

This event is only available on the Express Checkout Element.

**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
const expressCheckoutElement = checkout.createExpressCheckoutElement();
expressCheckoutElement.on('cancel', function() {
  // handle cancel event
});
```

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