Headless Shopify

On a headless Shopify storefront (Hydrogen, Next.js, or any custom frontend), Onward can't add Checkout+ through your theme. Instead, you load the Onward headless script, give it access to your cart, and tell it where your cart's checkout button is.

The integration has five steps:

1. Load the Onward headless script
2. Implement a StorefrontClient for your cart
3. Initialize Onward and attach it to your cart
4. Tell Onward when the cart changes
5. Hide the Onward product in your cart

Add this script to every page that shows a cart, replacing example.myshopify.com with your store's myshopify.com domain:

<script src="https://proxy.useonward.com/public/assets/onward_headless.js?shop=example.myshopify.com" async></script>

The script carries your store's Onward settings and defines window.initializeOnward and window.OnwardSetup. It dispatches an onward:loaded event on window once both are available.

Onward reads and updates your cart through an object you write that implements the StorefrontClient interface, usually on top of the Shopify Storefront API. Implement every method: which ones Onward calls depends on your store's Checkout+ settings, and those can change without a code change on your side.

The methods return a Cart, so you'll map your cart into that shape. A few details matter:

• fetchInsuranceProduct: look the Onward product up by its handle, onward-package-protection, not by ID, and include a price on every variant.
• requiresShipping: set it to true on each ProductVariant that ships. Onward only protects lines where it is true, so leaving it unset means nothing in the cart is protected.
• Subscriptions and line item properties: if your store uses them, pass sellingPlanIdentifier and properties through on cart lines. clearCart empties the cart and Onward re-adds every line, so anything you drop is lost.

Once the script has loaded, initialize Onward with your StorefrontClient, then use OnwardSetup to place the widget and connect your checkout button:

window.addEventListener('onward:loaded', () => {
  window.initializeOnward({ storefrontClient: new MyStorefrontClient() });

  const onward = new window.OnwardSetup();
  onward.addContainer('.cart-footer', { position: 'afterbegin' });
  onward.attachCheckoutButton('.cart-footer .checkout-button', {
    optOutSelector: '.cart-footer',
  });
});

Replace the selectors with your own:

• addContainer renders the Onward widget. We recommend placing it directly above the checkout button.
• attachCheckoutButton makes sure the cart is protected when the customer checks out, and adds a link inside optOutSelector for customers who want to check out without protection.

Call initializeOnward before creating OnwardSetup, and do both once per page load. OnwardSetup watches the page for elements that match your selectors, so a cart drawer that opens later or re-renders is picked up automatically.

By default, Onward continues to checkout by clicking your original checkout button. If your checkout is started some other way, pass a continueToCheckout function to attachCheckoutButton. AttachCheckoutOptions lists that and the other options.

If your storefront sells in more than one currency or language, also pass a locale to initializeOnward. Without it, Onward assumes USD and English.

Onward reads your cart once when it initializes. After that, pass it the updated cart every time it changes (items added or removed, quantities updated), so the protection price stays current and the right protection is added at checkout:

await window.onwardApp?.cartChanged(cart);

cart is the same Cart shape your StorefrontClient returns.

Onward can add its product to the cart as the customer heads to checkout, so it may still be there if they come back to your store. Onward doesn't control how your cart renders, so leave out lines for the product with the handle onward-package-protection when you display the cart. Keep them in the Cart you return from your StorefrontClient and pass to cartChanged; Onward needs to see them.

With products in the cart, check that:

• The Onward widget appears where you placed it and shows a protection price.
• The price updates when you change quantities or add and remove items.
• Checking out with the checkout button includes Onward protection on the order.
• The opt-out link reaches checkout without Onward protection.

If you get stuck, contact your Onward representative and we'll help you through it.