Skip to main content

Set up accelerated checkouts for React Native

This guide walks you through implementing accelerated checkouts in your React Native app. For an overview of accelerated checkouts and their benefits, see About accelerated checkouts.

Tip

For a complete example, all code samples in this tutorial are available in the React Native sample app.

Anchor to RequirementsRequirements

Anchor to Step 1: Install the packageStep 1: Install the package

Add the @shopify/checkout-sheet-kit package to your project:

Install package

npm install @shopify/checkout-sheet-kit@next

Anchor to Step 2: Configure shop settings and Apple Pay integrationStep 2: Configure shop settings and Apple Pay integration

Before you can use accelerated checkout buttons in your app, you will need to configure your shop settings and Apple Pay integration.

Anchor to Configure shop settingsConfigure shop settings

Set up the connection between the accelerated checkout buttons and your Shopify store by creating a Configuration object. If you're already using the ShopifyCheckoutSheetProvider for Checkout Sheet Kit, then you can extend your current configuration to include an acceleratedCheckouts object.

Shop configuration

import { Configuration, ShopifyCheckoutSheetProvider, ApplePayContactField } from "@shopify/checkout-sheet-kit";

const checkoutKitConfiguration: Configuration = {
acceleratedCheckouts: {
storefrontDomain: "your-shop.myshopify.com",
storefrontAccessToken: "your-storefront-access-token",
// Provide customer details if known, otherwise pass `undefined`
customer: {
email: "customer@example.com",
phoneNumber: "0123456789",
accessToken: "your-customer-access-token",
},
wallets: {
applePay: {
merchantIdentifier: "merchant.com.yourcompany",
contactFields: [ApplePayContactField.email, ApplePayContactField.phone],
},
},
},
}


function App() {
return (
<ShopifyCheckoutSheetProvider configuration={checkoutKitConfiguration}>
<App />
</ShopifyCheckoutSheetProvider>
)
}
Note

In cases where the customer is unknown, pass undefined for the customer argument. You can update the customer information when details are available.

Anchor to Specify required contact fields (Optional)Specify required contact fields (Optional)

You can specify which contact fields are required during Apple Pay checkout:

Required contact information

// Require both email and phone
contactFields: [ApplePayContactField.email, ApplePayContactField.phone]

// Require only email
contactFields: [ApplePayContactField.email]

// Require only phone
contactFields: [ApplePayContactField.phone]

// No contact fields required (default)
contactFields: []

Anchor to Restrict shipping countries (Optional)Restrict shipping countries (Optional)

You can restrict Apple Pay shipping addresses to specific countries using ISO 3166-1 alpha-2 country codes.

Important

The supportedShippingCountries parameter should only be used to specify supported shipping countries for Apple Pay when they differ from your store's other payment methods. If Apple Pay supports the same shipping countries as your store's general shipping configuration, this parameter is not needed—customers will automatically be directed to the Checkout Sheet to resolve any errors. Only use this parameter when Apple Pay has specific technical limitations that prevent shipping to certain countries that your store otherwise supports.

Restrict shipping countries

// Only allow shipping to US and Canada
wallets: {
applePay: {
merchantIdentifier: "merchant.com.yourcompany",
contactFields: [],
supportedShippingCountries: ["US", "CA"],
},
},

// Allow all countries (default behavior)
wallets: {
applePay: {
merchantIdentifier: "merchant.com.yourcompany",
contactFields: [],
// Omit supportedShippingCountries
},
},

Anchor to Step 3: Add accelerated checkout buttons to your appStep 3: Add accelerated checkout buttons to your app

Now that your configuration is complete, you can add accelerated checkout buttons to your cart and product pages.

Anchor to Implement accelerated checkout buttons on cart pageImplement accelerated checkout buttons on cart page

You can display the accelerated checkout buttons on the cart page by passing the cart ID to the component:

Cart page implementation

import { AcceleratedCheckoutButtons } from "@shopify/checkout-sheet-kit";

function CartView() {
return (
<AcceleratedCheckoutButtons
cartID="gid://shopify/Cart/123"
/>
)
}

Anchor to Implement accelerated checkout buttons on product pagesImplement accelerated checkout buttons on product pages

You can display the accelerated checkout buttons on product pages by passing the product variant ID and quantity to the component. This creates a new checkout session with only the specified item.

Product page implementation

import { AcceleratedCheckoutButtons } from "@shopify/checkout-sheet-kit";

function ProductView() {
return (
<AcceleratedCheckoutButtons
variantID="gid://shopify/ProductVariant/123"
quantity={1}
/>
)
}

Anchor to Step 4: Customize the buttonsStep 4: Customize the buttons

Anchor to Customize wallet optionsCustomize wallet options

Configure which payment options are displayed. By default, both available payment buttons (Shop Pay and Apple Pay) are rendered. Render order is determined by the order you list them in the wallets prop.

Customize wallet options

// Default: Display all available buttons
<AcceleratedCheckoutButtons cartID="gid://shopify/Cart/123" />

// Display only Shop Pay
<AcceleratedCheckoutButtons
cartID="gid://shopify/Cart/123"
wallets={[AcceleratedCheckoutWallet.shopPay]}
/>

// Display only Apple Pay
<AcceleratedCheckoutButtons
cartID="gid://shopify/Cart/123"
wallets={[AcceleratedCheckoutWallet.applePay]}
/>

// Display both Shop Pay and Apple Pay, in the order you specify
<AcceleratedCheckoutButtons
cartID="gid://shopify/Cart/123"
wallets={[
AcceleratedCheckoutWallet.shopPay,
AcceleratedCheckoutWallet.applePay,
]}
/>

Anchor to Modify the Apple Pay button labelModify the Apple Pay button label

The applePayLabel might be used to modify the label in accordance to the PayWithApplePayLabel. Defaults to .plain.

Modify Apple Pay label

<AcceleratedCheckoutButtons
cartID="gid://shopify/Cart/123"
applePayLabel={ApplePayLabel.buy} />

Anchor to Customize button appearanceCustomize button appearance

You can customize the visual appearance of the accelerated checkout buttons to match other CTAs in your app using props.

Anchor to Corner radiusCorner radius

Customize the corner radius of all checkout buttons with the cornerRadius prop. The default radius is set to 8px. Here are some examples:

Customize corner radius

// Default radius (8px) - works well with most modern app designs
<AcceleratedCheckoutButtons cartID="gid://shopify/Cart/123" />

// Match rounded buttons (e.g., if your app uses pill-shaped CTAs)
<AcceleratedCheckoutButtons
cartID="gid://shopify/Cart/123"
cornerRadius={16}
/>

// Match sharp, minimal designs
<AcceleratedCheckoutButtons
cartID="gid://shopify/Cart/123"
cornerRadius={4}
/>

// Match square buttons
<AcceleratedCheckoutButtons
cartID="gid://shopify/Cart/123"
cornerRadius={0}
/>

Anchor to Step 5 (Recommended): Handle component statesStep 5 (Recommended): Handle component states

The accelerated checkout buttons depend on the shop object from the Storefront API. This request is initiated by the first AcceleratedCheckoutButtons rendered, the response is stored in shared memory amongst other instances of the buttons for the duration of the app session.

Accelerated checkouts delegates to you for loading and error states that best match the style of your application. To facilitate this you may listen to the onRenderStateChange event callback.

Component Lifecycle

import { useState } from "react";
import { RenderState } from "@shopify/checkout-sheet-kit";

function CheckoutButtons() {
const [renderState, setRenderState] = useState<RenderState>(RenderState.loading);

function onRenderStateChange(state: RenderState) {
setRenderState(state);
}

if (renderState === RenderState.loading) {
return <ProgressView />;
}

if (renderState === RenderState.error) {
return <ErrorState />;
}

return (
<AcceleratedCheckoutButtons
cartID="gid://shopify/Cart/123"
onRenderStateChange={onRenderStateChange}
/>
);
}

Anchor to Step 6 (Optional): Handle checkout lifecycle eventsStep 6 (Optional): Handle checkout lifecycle events

You can respond to checkout lifecycle events using the provided event handlers:

Event handling

<AcceleratedCheckoutButtons
cartID="gid://shopify/Cart/123"
onComplete={(event) => {
// Navigate to order details screen `event.orderDetails.id`
}}
onFail={(error) => {
// Show error alert
}}
onCancel={() => {
// Reset state
}}
onWebPixelEvent={(event) => {
// Track analytics event
}}
onClickLink={(url) => {
// Handle external links
}}
/>
Note

When Apple Pay encounters an error, the SDK automatically falls back to the full checkout sheet before triggering the onFail() handler. This built-in recovery mechanism ensures that customers can complete their purchase using alternative payment methods.

Anchor to Clear cart state after checkoutClear cart state after checkout

Cart IDs expire after accelerated checkout completes. To prevent subsequent failures after a successful checkout, you must clear your local cart state in the onComplete handler. For example:

Clear cart state after checkout

<AcceleratedCheckoutButtons
cartID="gid://shopify/Cart/123"
onComplete={(event) => {
// Clear cart state
}}
/>

Anchor to TroubleshootingTroubleshooting

If you encounter issues with accelerated checkout buttons, try these common solutions:

Anchor to Apple Pay sheet closes automaticallyApple Pay sheet closes automatically

If the Apple Pay sheet closes automatically, without user interaction, then the issue might be with your merchant ID configuration.

  1. Verify your merchant ID is registered in the Apple Developer Portal.
  2. Confirm the merchant ID is added to your Xcode project under Signing & Capabilities > Apple Pay > Merchant IDs.
Was this page helpful?