---
title: Preload checkout
description: >-
  Load checkout in the background so it's ready before the buyer needs it, and
  observe the preload state.
source_url:
  html: 'https://shopify.dev/docs/storefronts/mobile-next/checkout-kit/preloading'
  md: 'https://shopify.dev/docs/storefronts/mobile-next/checkout-kit/preloading.md'
---

# Preload checkout

Preloading fetches checkout in the background. If the preload is ready when the buyer taps **Checkout**, Checkout Kit uses it to reduce loading time.

Without preload

With preload

***

## Requirements

* [Checkout Kit](https://shopify.dev/docs/storefronts/mobile/checkout-kit) installed in your app.
* A valid `checkoutUrl` from [Build a mobile storefront](https://shopify.dev/docs/storefronts/mobile/build-mobile-storefront) or a [cart permalink](https://shopify.dev/docs/apps/build/checkout/create-cart-permalinks).

***

## Preload checkout

When the buyer navigates to the cart, call `preload()` to start fetching checkout in the background. By the time they tap **Checkout**, the page is ready:

## Preload checkout

##### Swift

```swift
ShopifyCheckout.preload(checkout: checkoutURL)
```

##### Kotlin

```kotlin
ShopifyCheckout.preload(checkoutUrl, activity)
```

##### React Native

```javascript
const shopifyCheckout = useShopifyCheckout();
shopifyCheckout.preload(checkoutUrl);
```

**Caution:**

Avoid calling `preload()` on every add-to-cart action. Frequent preloading triggers background network requests, increases memory usage, and might trigger Storefront API rate limits.

***

## Observe the preload state

`preload()` returns an observable handle whose state moves through `idle`, `loading`, `ready`, or `failed` with a reason. An expired preload returns to `idle` with an `expired` reason on every platform: `.idle(reason: .expired)` in Swift, `PreloadState.Idle(IdleReason.Expired)` in Kotlin, and `{type: 'idle', reason: 'expired'}` on React Native. Use it to show progress or to fall back gracefully when a preload fails. Don't gate the checkout button on it: `present()` reuses a preload that's still loading, so the buyer sees its loading state, and cold-loads checkout whenever a preload is missing, expired, or failed.

A failed preload never fires the checkout failure callback. Presentation falls back to a cold load, and the buyer sees a regular loading state.

## Observe the preload state

##### Swift

```swift
let preload = ShopifyCheckout.preload(checkout: checkoutURL)
preload?.onStateChange = { state in
  if case .ready = state {
    // The preload is ready for presentation
  }
}
```

##### Kotlin

```kotlin
val preload = ShopifyCheckout.preload(checkoutUrl, activity) { state ->
    if (state is PreloadState.Ready) {
        // The preload is ready for presentation
    }
}
```

##### React Native

```javascript
const subscription = shopifyCheckout.preload(checkoutUrl, {
  onStateChange: (state) => {
    if (state.type === 'ready') {
      // The preload is ready for presentation
    }
  },
});
```

***

## Manage preloaded checkouts

Preloading renders checkout in a background web view. The preloaded checkout reflects the cart, configuration, and appearance at the time you call `preload()`. When you present the same checkout, it moves to the foreground.

A preloaded checkout is reused only when what you present matches what you preloaded. The preload is discarded, and presentation falls back to a cold load, when:

* **The URL differs.** The match is on the fully parameterized URL, so a changed cart, a new discount code, or different query parameters all miss the cache.
* **The appearance differs.** Appearance is part of the preloaded page, so set it before you preload rather than at presentation time.
* **You call `configure()` again.** Any configuration change clears the preload, including turning preloading off with `preloading.enabled`. Configure first, then preload.
* **You call `clearPreload()`,** or checkout completes, or an unrecoverable checkout error occurs.

If the cart changes after preloading, call `preload()` again to refresh, or call `clearPreload()` to clear the cache. Completing checkout invalidates the preload automatically, as does an unrecoverable checkout error. Checkout Kit might delay or skip preloading during high traffic; if preloading doesn't complete before presentation, buyers see a loading state.

***

## Disable preloading

To disable preloading, set `enabled` to `false`. You might disable it when a buyer enables data saver mode. When disabled, Checkout Kit ignores all calls to `preload()`:

## Disable preloading

##### Swift

```swift
ShopifyCheckout.configure {
    $0.preloading.enabled = false // defaults to true
}
```

##### Kotlin

```kotlin
ShopifyCheckout.configure {
    it.preloading = Preloading { enabled = false } // defaults to true
}
```

##### React Native

```jsx
import { ShopifyCheckoutProvider } from '@shopify/checkout-kit-react-native';

const configuration = { preloading: false };

<ShopifyCheckoutProvider configuration={configuration}>
  <App />
</ShopifyCheckoutProvider>
```

***

## Next steps

[Monitor checkout lifecycle\
\
](https://shopify.dev/docs/storefronts/mobile/checkout-kit/monitor-checkout-lifecycle)

[Handle what happens after a preloaded checkout completes, fails, or is dismissed.](https://shopify.dev/docs/storefronts/mobile/checkout-kit/monitor-checkout-lifecycle)

[Configure checkout branding\
\
](https://shopify.dev/docs/storefronts/mobile/checkout-kit/configuration)

[Choose between storefront branding and Checkout Kit's built-in light or dark styling.](https://shopify.dev/docs/storefronts/mobile/checkout-kit/configuration)

[Accelerated checkouts\
\
](https://shopify.dev/docs/storefronts/mobile/checkout-kit/accelerated-checkouts-overview)

[Add Shop Pay and Apple Pay buttons for one-tap purchases on product and cart pages.](https://shopify.dev/docs/storefronts/mobile/checkout-kit/accelerated-checkouts-overview)

***