Skip to main content
The headless SDK is an npm package that runs your ABConvert tests on a storefront you build yourself: Hydrogen, Next.js, or any stack on the Storefront API. On a custom storefront your code renders every page, so ABConvert cannot change the page for you. The SDK does four jobs instead:
  1. Assign. It puts each visitor in a test group, on your server or in the browser, and keeps them there on every visit.
  2. Read. It gives your code the visitor’s test group, test price, shipping rates, and offers, so you render them.
  3. Connect the cart. It gives you the cart attributes that make Shopify checkout apply the test, and that tie the order to the test group.
  4. Track. It records page views, add to cart, and custom events for your results.
You integrate once. After that, price, shipping, offer, checkout, and URL redirect tests need no code change: you create them, launch them, and read results in the ABConvert admin, as on any other store. Only a feature test (coming soon) needs code, once per feature, because you build its versions. This page is for developers who build a custom storefront.

​
When to use it

  • Your storefront runs on Hydrogen and you want to test a $49 price against $59 on your best-selling product.
  • Your Next.js storefront shows a free shipping bar, and you want to test a $50 threshold against $75.
  • You want to pair a higher price with free shipping in one combined test.
  • You run a checkout test and your cart is created through the Storefront API.
  • You built a new hero section in React and want to test it against the current one.

​
When not to use it

  • Your storefront uses a Shopify theme. ABConvert works there with no code. If you need to read test data in theme JavaScript, use the JavaScript API instead.
  • You want to create tests or read results from your backend. Use the REST API instead.

​
What you can test

​
Before you start

You need:
  • ABConvert installed on your Shopify store.
  • A storefront that creates carts with the Storefront API and sends visitors to Shopify checkout.
  • Your store’s myshopify.com domain.
  • The headless SDK turned on for your store. Ask your ABConvert contact.
  • A storefront key, from Integrations > Headless Storefront in ABConvert.
  • A server on Node.js 20 or later, Oxygen, Cloudflare Workers, or Vercel Edge. On Next.js, see supported versions. React 17 or later for the React bindings.
  • A test in the ABConvert admin. A test in preview is enough to integrate against.

​
How it works

Create a client for each request. The SDK loads your tests once per server and shares them, and every read answers from memory. The recommended setup assigns on the server, so the first HTML already shows the right test group.
  1. Your server creates the client from the incoming request.
  2. Your loaders and components read the visitor’s test config from the client, such as their test group or test price, and render it.
  3. Your cart code writes the client’s cart attributes to the Storefront API cart.
  4. Shopify checkout reads those attributes and applies the test.
  5. ABConvert ties the order to the visitor’s test group.
The diagram shows one visit, from the first page to the order. The client on the server, useABConvert() in a component, and a browser-only client share one API, with the same names and behavior. The few methods that exist on one side only are marked in the reference.

​
Pick your stack

Each guide is a complete setup for its stack, in that stack’s code only. Follow one.

Next.js

App Router, with test groups assigned in the middleware.

Hydrogen

Test groups assigned in your loaders, with Hydrogen’s analytics and consent.

Other stacks

Any server on the Storefront API, the browser only, or without React.

​
After setup

Your stack guide covers everything every storefront needs. Do these when the condition applies to yours:

​
Guides

Prices, shipping, and offers

Render what the visitor’s test group gets.

Cart and checkout

Make checkout apply the test, including express checkout.

URL redirect tests

Redirect on your server.

Test groups

Read which test group a visitor is in.

Feature tests

Coming soon: test a change you build yourself.

Targeting

How audiences work, and what your storefront supplies.

Tracking and cookies

What the SDK tracks and stores.

Preview and check

See one test group and confirm checkout applies it.

Loading and failures

What a visitor sees if the SDK cannot load.

Reference

Every entry point, method, and option.

​
Common mistakes

  • Not writing the cart attributes. The page shows the test price and checkout charges the original price. The fix: write getCartAttributes() on every cart. See Connect the cart.
  • Caching HTML that contains one test group’s version. A full-page cache or a CDN then serves that version to every visitor. The fix: follow your stack’s caching page, Next.js or Hydrogen. On other stacks, cache per test group, or leave tested pages uncached.
  • Showing a test price without calling trackExposure. The visitor is counted as assigned but not as having experienced the test. The fix: call it once the price is on screen. See Record a price exposure.
Each guide lists the mistakes for its own step.

​
FAQ

The cart is missing ABConvert’s attributes. Write getCartAttributes() when you create the cart and each time you update it. See Connect the cart.
First check that you passed the product variant ID, not the product ID. Otherwise null means no test price applies to this visitor. Render the Storefront API price.
The browser did not receive the server’s state. Pass getPageState() from your loader to ABConvertProvider, and add getSetCookieHeaders() to the loader’s response so the visitor ID cookie is set.
No. The SDK keeps the visitor ID and its decisions in cookies and reads them on every request. See Cookies and storage.