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.

Anchor to RequirementsRequirements

• Checkout Kit installed in your app.
• A valid checkoutUrl from Build a mobile storefront or a cart permalink.

Anchor to Preload checkoutPreload 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:

ShopifyCheckout.preload(checkout: checkoutURL)

ShopifyCheckout.preload(checkoutUrl, activity)

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

Anchor to Observe the preload stateObserve 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.

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

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

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

Anchor to Manage preloaded checkoutsManage 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.

Anchor to Disable preloadingDisable 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():

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

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

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

const configuration = { preloading: false };

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

Anchor to Next stepsNext steps

Monitor checkout lifecycle

Handle what happens after a preloaded checkout completes, fails, or is dismissed.

Configure checkout branding

Choose between storefront branding and Checkout Kit's built-in light or dark styling.

Accelerated checkouts

Add Shop Pay and Apple Pay buttons for one-tap purchases on product and cart pages.