Headless SDK reference

This page lists every export of @abconvert/headless by entry point. For what the SDK is for and how to set it up, read the overview and your stack guide first. IDs are accepted as the Storefront API returns them, gid://shopify/ProductVariant/47522361606401, or as the number, '47522361606401'. Test IDs are the number the ABConvert admin shows, as a string or a number. Returned IDs, such as Assignment.experimentId, Price.productId, and Price.variantId, are always strings holding the number: '47522361606401'.

Entry points

Any stack
Next.js
Hydrogen 2026.10 and later
Hydrogen before 2026.10

Entry points

// The client: runs on the server, at the edge, or in the browser
import { createABConvert, hydrateABConvert } from '@abconvert/headless';

// The React bindings
import { ABConvertProvider, useABConvert } from '@abconvert/headless/react';

Entry points

// The middleware and the client for a page or server action
import { abconvertMiddleware, planMiddleware, createABConvert } from '@abconvert/headless/next';

// The React bindings
import { ABConvertProvider, useABConvert } from '@abconvert/headless/react';

Entry points

// The client for your loaders, the React bindings with Hydrogen's analytics and consent, and the full-page cache guard
import { createABConvert, ABConvertProvider, useABConvert, keepPrivateWhenTested } from '@abconvert/headless/hydrogen';

// The cart attributes, for a cart that changes in the browser
import { ABConvertCartAttributes, useCartReadyForCheckout } from '@abconvert/headless/hydrogen';

Entry points

// The client for your loaders and the full-page cache guard
import { createABConvert, keepPrivateWhenTested } from '@abconvert/headless/hydrogen';

// The React bindings, placed inside Analytics.Provider
import { ABConvertProvider, useABConvert } from '@abconvert/headless/hydrogen/analytics-provider';

createABConvert

Creates the client. What you pass decides which client you get:

You pass	You get	Runs on
`request`	A server client for that visitor. Reads the visitor ID, URL, and country from the request. Adds `getPageState`, `isPageTested`, and `isTesting`.	Server
`pageKey`	A page client for the key’s test groups. Reads no request and has no visitor. Adds `getPageState`. See A client made with pageKey.	Server
Neither, in a browser	A browser client. Assigns the visitor after the tests load, writes the SDK’s cookies, and starts tracking. Resolves once the visitor is assigned.	Browser

Signature

createABConvert(options: ABConvertOptions & { request: Request | { headers, url } }): Promise<ServerABConvert>
createABConvert(options: ABConvertOptions & { pageKey: string }): Promise<PageABConvert>
createABConvert(options: ABConvertOptions): Promise<ABConvert>

ServerABConvert adds getPageState, isPageTested, and isTesting; PageABConvert adds getPageState. Both are exported, so TypeScript knows which methods your client has. Never rejects, with one exception: a client made with pageKey rejects when the tests the key names cannot be loaded. When the tests cannot be loaded for a request, the client answers as the original store. See Loading and failures.

Options

string

required

Your myshopify.com domain: 'your-store.myshopify.com'.

string

required

A storefront key from Integrations > Headless Storefront in ABConvert. It tells ABConvert which store’s tests to load, and is safe to ship in storefront code.

Request | { headers, url }

The incoming request. Required on the server. Pass the Fetch Request, or { headers, url } when your framework has none.

string

ISO 3166-1 alpha-2 code of the country your storefront shows prices for, the same value you pass to the Storefront API in @inContext. Defaults to your store’s default country. See Prices by country.

Customer

The signed-in customer, for customer conditions. Every field is optional. See Customer.

Show fields

boolean

Defaults to true when customer is passed.

string[]

tags on the customer.

number

numberOfOrders on the customer.

number

In your store currency.

number

default:"1000"

Milliseconds to wait for your tests when the server holds no copy yet. See If loading is slow.

number

default:"60"

Seconds a loaded copy of your tests stays fresh. See How the copy refreshes.

(error: Error) => void

Called when your tests cannot be loaded.

Whether the visitor allows analytics. Without it, the SDK reads Shopify’s _tracking_consent cookie when the visitor has one, and otherwise treats analytics as allowed. See Consent.

boolean

default:"false"

true when your storefront loads Shopify’s Customer Privacy API. The SDK then tracks nothing until the visitor answers. The Hydrogen entries set it for you.

string

Builds the client from a page key instead of a request: getPageKey() from the server client, or the segment the Next.js middleware rewrote to. '' is a page no test changes.

boolean

default:"false"

true when your product pages show no price but their own product’s. A product page’s key then carries only the price tests that include that product. Leave it unset when a related product’s price appears on the page.

A client made with pageKey

A client made with pageKey renders a page a cache may serve to everyone in its test groups, so it has no visitor:

createABConvert rejects when the tests the key names cannot be loaded. It waits up to 10 seconds, or timeout if that is longer. An empty key never rejects.
Price and assignment reads answer for the key’s test groups. Shipping rates and offers are not in a page key, so those reads return nothing.
getPageState() replaces getClientState(), which throws.
getCartAttributes(), getCartLineAttributes(), and getCheckoutUrl() throw. Create a client from the request for them.
getVisitorId() returns '', getRedirectUrl() returns null, and getSetCookieHeaders() returns [].

Methods

The server client, the browser client, and useABConvert() in a component share one API. “Runs on” marks the methods that do something on one side only; elsewhere they return the empty value shown.

Method	Returns	Runs on
`getAssignment(experimentId)`	`Assignment \| null`	Both
`getAssignments()`	`Assignment[]`	Both
`getFeature(key)` (coming soon)	`Assignment \| null`	Both
`getPriceByVariantId(variantId, options?)`	`Price \| null`	Both
`getPriceByProductId(productId, options?)`	`Price \| null`	Both
`formatPrice(amount, currency?)`	`string`	Both
`getShippingRates(options?)`	`ShippingRate[] \| null`	Both
`getFreeShippingThreshold(options?)`	`FreeShippingThreshold \| null`	Both
`getOffers()`	`Offer[]`	Both
`getVisitorId()`	`string`	Both
`getCountry()`	`string`	Both
`forceTestGroup(experimentId, index)`	`void`	Both
`clearForcedTestGroup(experimentId)`	`void`	Both
`getCartAttributes()`	`CartAttribute[]`	Both
`getCartLineAttributes()`	`CartAttribute[]`	Both
`getCheckoutUrl(options)`	`string`	Both
`getPageKey()`	`string`	Both
`getRedirectUrl(url)`	`string \| null`	Server
`getClientState()`	`ClientState`	Server
`getPageState()`	`PageState`	Server
`isPageTested()`	`boolean`	Server, from a request
`isTesting()`	`boolean`	Server, from a request
`getSetCookieHeaders()`	`string[]`	Server
`refreshTests()`	`Promise<void>`	Server
`track(name, payload?)`	`void`	Browser
`trackExposure(experimentId)`	`void`	Browser
`setConsent(consent)`	`void`	Browser

getAssignment

Returns the visitor’s Assignment for one test, or null when the visitor is not in it. See Read an assignment.

string | number

required

The test ID shown in the ABConvert admin: '49603'.

getAssignments

Returns one Assignment per test the visitor is in. [] when they are in none.

getFeature

Coming soon. Returns the visitor’s Assignment in the running feature test with this key, or null. Until feature tests ship it returns null for every key.

string

required

The feature key set on the test: 'home-hero'.

getPriceByVariantId

Returns the visitor’s Price for one product variant, or null when the visitor sees the original price: the product variant is in no price test, or the visitor is not in its test. A visitor in Control gets the original price as a Price. See Show a test price.

string | number

required

The product variant ID.

PriceOptions

Show fields

string

ISO 3166-1 alpha-2 code. Reads that country’s price instead of the client’s country.

getPriceByProductId

Returns a Price for one product, from its product variants’ prices, or null in the same cases as getPriceByVariantId.

string | number

required

The product ID.

PriceOptions

Show fields

string

ISO 3166-1 alpha-2 code. Reads that country’s price instead of the client’s country.

'min' | 'max' | 'first'

default:"'min'"

Which product variant’s price to return. 'min' and 'max' pick among the product variants the test prices for this visitor. 'first' picks the product’s first product variant, or the first one the test prices.

formatPrice

Returns amount formatted in currency, such as '$62.70', in the locale the page rendered in, so the server and the browser format alike.

number

required

string

ISO 4217 code: 'USD'. Defaults to your store’s currency.

getShippingRates

Returns every ShippingRate the visitor’s test group offers, null when the visitor is in no shipping test, or [] when the test group has no rates or zone names a zone the test does not have. See Show shipping rates and offers.

ShippingOptions

Show fields

string

A shipping zone name as set in the test: 'United States'. Defaults to every zone.

getFreeShippingThreshold

Returns the FreeShippingThreshold the visitor’s test group gets, or null when the visitor is in no shipping test or no single threshold exists.

ShippingOptions

Show fields

string

A shipping zone name as set in the test.

getOffers

Returns every Offer the visitor’s test group gets. [] when the visitor is in no offer test, or their test group has no offer.

getVisitorId

Returns the visitor ID the SDK keeps in the abconvert-visitor cookie. '' on a client made with pageKey.

getCountry

Returns the country the client prices for: the country you passed, or the store’s default.

forceTestGroup

Shows one test group to this visitor, for the rest of the visit. A forced visit is left out of results. On Next.js, a force on the server lasts only for that render. See Preview a test group.

string | number

required

The test ID shown in the ABConvert admin.

number

required

The test group’s position counting from 0: 0 is Control, 1 is Variant A.

clearForcedTestGroup

Undoes forceTestGroup for one test.

string | number

required

The test ID shown in the ABConvert admin.

getCartAttributes

Returns the cart attributes that make Shopify checkout apply the visitor’s tests: one CartAttribute per key. Send them with the cart’s own attributes on every cartAttributesUpdate. Throws on a client made with pageKey.

getCartLineAttributes

Returns the same data as CartAttribute entries for a cart line. Add them to each line you add. Throws on a client made with pageKey.

getCheckoutUrl

Returns a Shopify cart permalink that lands in checkout with the visitor’s test groups applied. Build it when you render the button; never share or cache it. Throws on a client made with pageKey. See Checkout URLs.

CheckoutUrlOptions

required

Show fields

CheckoutLine[]

required

The lines to check out: [{ variantId: '47522361606401', quantity: 1 }]. Line attributes reach the first line only.

'shop_pay'

Opens Shop Pay checkout.

getPageKey

Returns the page key: the test groups this page renders for, the same for every visitor in them. '' when no test changes the page. In the browser, a client built from getPageState() returns the key the page was rendered for, and one built from getClientState() returns ''.

getRedirectUrl

Server only. Returns where a URL redirect test sends this visitor, as a same-origin path, or null when they stay: they are in Control or outside the test, the URL is not part of a test, or the visitor is a known crawler. null in the browser.

string

required

The URL the visitor requested: request.url.

getClientState

Server only. Returns the ClientState that hands this visitor’s page to the browser. It holds the visitor, so a page that carries it renders per visitor and must not be cached. Pass it to the provider’s state. Throws on a client made with pageKey.

getPageState

Server only. Returns the PageState that hands the page to the browser with nothing about the visitor, so a cached page can carry it. From a client made from a request, it carries the tests the client’s reads touched, as the visitor saw them; from a client made with pageKey, the key’s test groups. Pass it to the provider’s pageState.

isPageTested

Server only, on a client made from a request. Returns true when a test that runs or is in Preview can change this page for some visitor, whatever this visitor’s test groups: a price test prices a product the URL shows, a URL redirect test starts or lands on the page, a read on this client returned a test’s data, getClientState() was read, or the request is a preview session. A shared cache must then not keep one copy of the page for everyone.

isTesting

Server only, on a client made from a request. Returns true while any test runs for your store, whatever the page, and in a preview session.

getSetCookieHeaders

Server only. Returns the Set-Cookie values the SDK needs on the response, only for cookies that changed, such as on a first visit. [] in the browser and on a client made with pageKey. On Next.js, the middleware sets them for you.

refreshTests

Server only. Fetches a fresh copy of your tests on this server now. If the fetch fails, the old copy is kept. See How the copy refreshes.

track

Browser only. Records a storefront event for the visitor. Does nothing on the server. See Page views and add to cart.

string

required

'page_viewed', 'product_viewed', 'product_added_to_cart', or the name of a custom event in ABConvert.

object

{ productId, variantId } for product_viewed, { variantId, quantity } for product_added_to_cart, none for page_viewed.

trackExposure

Browser only. Records that the visitor experienced a test, once per test per visit. Call it once a test price or an offer is on screen. See Exposure.

string | number

required

price.experimentId or offer.experimentId from the object you rendered.

setConsent

Browser only. Updates the visitor’s answer to your cookie banner. What the SDK held is sent when analytics becomes true, and dropped when it becomes false. See Consent.

Browser client

hydrateABConvert

Builds the browser client from what the server handed over, without React. ABConvertProvider does this for you. See Other stacks.

Signature

hydrateABConvert(state: ClientState | PageState | null, options?: HydrateOptions): BrowserABConvert

ClientState | PageState | null

required

getClientState() or getPageState() from the server, as the page carried it.

HydrateOptions

Show fields

(assignment: Assignment) => void

Runs once for each test the visitor is in, on every page load, once the visitor allows analytics. Not for forced or preview assignments.

boolean

default:"false"

Hold all tracking until Shopify’s Customer Privacy API loads and allows analytics.

The browser client has every method, plus:

void

Begins tracking: reports what is pending once consent allows. Call it once the page has loaded. Calling it again does nothing.

void

Stops waiting for the visitor’s consent. What is held stays held.

Calls listener after a forced test group changes what the reads return. Returns the function that removes the listener.

React

From @abconvert/headless/react. On Hydrogen, import both from the Hydrogen entry instead.

ABConvertProvider

Shares the client with every component under it and records which test groups the visitor saw. Pass exactly one of state, pageState, or options. A server component can render it directly.

ClientState

getClientState() from your server: a page rendered for its visitor.

PageState

getPageState() from your server: a page rendered for its test groups, which a cache may serve to everyone in them. The provider reads the visitor from their cookies once it mounts.

ABConvertOptions

Browser-only mode, with no server: the createABConvert options without request. The tests load after the page does, and isReady is false until then. See Browser only.

(assignment: Assignment) => void

Runs once for each test the visitor is in, on every page load, once the visitor allows analytics. Not for forced or preview assignments. See Send test groups to another tool.

boolean

default:"false"

Hold all tracking until Shopify’s Customer Privacy API loads and allows analytics. See Consent.

useABConvert

Returns the client for the nearest provider: every method, plus isReady.

boolean

false only in browser-only mode, until the tests load and the visitor is assigned. Hide prices until it is true.

Next.js

From @abconvert/headless/next. See the Next.js guide and Next.js caching and CDN.

abconvertMiddleware

Sets the SDK’s cookies, passes the visitor on to your pages, redirects for a URL redirect test, rewrites a tested page to its page key, and sets cache-control where a shared cache must not keep the response. Returns the response for Next.js to send. Call it from your middleware or proxy function.

Signature

abconvertMiddleware(request: NextRequest, options: NextOptions): Promise<NextResponse>

NextRequest

required

NextOptions

required

The createABConvert options except request and pageKey, plus:

Show fields

string

default:"'abconvert'"

The path segment tested pages are rewritten under. Pick one that none of your routes uses, and name your app/abconvert folder after it.

true once your CDN includes the abconvert-key cookie in its cache key. A tested page then stays cacheable at the CDN. See Cache tested pages at your CDN.

planMiddleware

What abconvertMiddleware would do with the request, as data, for a middleware of your own that also rewrites. Apply every field to your response, as the sample does. Resolves to null for a request that is not a page, such as an image.

Signature

planMiddleware(request: Request, options: NextOptions): Promise<MiddlewarePlan | null>

Takes the same arguments as abconvertMiddleware. The plan has these fields:

string

The absolute URL to redirect to. Absent when the visitor stays.

307 | 308

307 for a URL redirect test, 308 for a direct visit to the rewrite prefix. Present with redirect.

string

The page key path to render instead, /<prefix>/<page key><path><query>. Present when a test changes the page, and on a server action from such a page.

string

The page key, '' when no test changes the page. Absent on a redirect, on a request left alone, and on a server action from a page no test changes.

Headers

The request headers to render the page with. Absent on a redirect. For a server action, they keep the action on the same copy of your tests as the page the visitor saw.

string[]

Set-Cookie values to append to the response.

Record<string, string>

Headers to set on the response, such as cache-control: private.

createABConvert on Next.js

The client a layout, page, or server action renders with. Never sets cookies; the middleware does.

Signature

createABConvert(options: NextOptions & { pageKey: string }): Promise<PageABConvert>
createABConvert(options: NextOptions): Promise<ServerABConvert>

NextOptions

required

The createABConvert options except request. With pageKey, the client for a cached page: it reads no request, so the page stays static. Without it, the client for the request the middleware prepared, which makes the page dynamic; use it in a server action or route handler.

Hydrogen

From @abconvert/headless/hydrogen on 2026.10 and later, or @abconvert/headless/hydrogen/analytics-provider before 2026.10. See the Hydrogen guide.

createABConvert on Hydrogen

The server client for a loader. The same as createABConvert with request, except that it tracks nothing until Shopify’s Customer Privacy API wrote the visitor’s answer, and sets a cookie only when one changed, so a route that renders no test’s data carries no Set-Cookie and can stay in the full-page cache. Exported by both Hydrogen entries.

Signature

createABConvert(options: ABConvertOptions & { request: Request }): Promise<ServerABConvert>

ABConvertOptions

required

The createABConvert options. request is required; expectCustomerPrivacy is set for you.

ABConvertProvider on Hydrogen

The React provider, which also listens to Hydrogen’s analytics for page views, product views, and add to cart, and waits for the visitor’s consent. On 2026.10 and later, render it below Hydrogen’s ShopifyScripts; before 2026.10, inside Analytics.Provider. Takes the provider’s props except expectCustomerPrivacy, which is always on.

keepPrivateWhenTested

Turns a public Cache-Control or Oxygen-Cache-Control header into private when a test can change the route, when the response sets a cookie, or when the client could not load your tests. Call it on the response headers of a route that opts into Oxygen’s full-page cache, after the loader’s reads. Returns true when it changed a header. See Hydrogen full-page cache.

Signature

keepPrivateWhenTested(headers: Headers, client: ServerABConvert): boolean

Headers

required

Your route’s response headers, with its cache setting already on them.

ServerABConvert

required

The client from createABConvert for this request.

ABConvertCartAttributes

Writes ABConvert’s cart attributes to the cart whenever it lacks one or holds an older value, and keeps the cart’s other attributes. It waits until no cart change is in flight. When an update fails, it tries again after 1, 2, 4… seconds, up to 30. Render it once, inside both CartProvider and ABConvertProvider. Exported by @abconvert/headless/hydrogen only, for 2026.10 and later, where the cart changes in the browser. See Write the cart attributes.

Signature

<ABConvertCartAttributes useCart={useCart} />

UseCart

required

The useCart hook that createCartComponents returns in your app.

useCartReadyForCheckout

Returns true once the cart carries ABConvert’s current attributes. Checkout charges what they say, so hold your checkout button until then. Exported by @abconvert/headless/hydrogen only, for 2026.10 and later.

Signature

useCartReadyForCheckout(useCart: UseCart): boolean

UseCart

required

The useCart hook that createCartComponents returns in your app.

Objects

Assignment, TestGroup, Price, ShippingRate, FreeShippingThreshold, and Offer are the same objects as on the JavaScript API, described under its Objects. The headless SDK adds these.

Feature test fields

For a feature test, coming soon:

string

The feature key set on the test. Absent for every other test type.

Record<string, string | number | boolean>

The values set for that test group. {} for every other test type.

CartAttribute

string

CheckoutLine

string | number

The product variant ID.

number

ClientState

What getClientState() hands the browser: the visitor, their test groups, and the tests cut to what they see. It identifies the visitor, so a page that carries it is that visitor’s alone. Pass it to the provider’s state or to hydrateABConvert as it is.

PageState

What getPageState() hands the browser. It holds nothing about the visitor, so a cached page can carry it. Pass it to the provider’s pageState or to hydrateABConvert as it is.

string

The key the page was rendered for. '' when no test changes the page.

string

The country the page was priced for.

Assignment[]

The key’s test groups: what the page renders for.

TypeScript

Every type on this page is exported. The options are ABConvertOptions, and NextOptions and MiddlewarePlan from @abconvert/headless/next. UseCart, from @abconvert/headless/hydrogen, is the type of the useCart argument. createABConvert returns an ABConvert: a ServerABConvert when made from a request, a PageABConvert when made with pageKey, and hydrateABConvert returns a BrowserABConvert. The objects are Assignment, TestGroup, Price, ShippingRate, FreeShippingThreshold, Offer, CartAttribute, CheckoutLine, ClientState, and PageState.

import type { ABConvertOptions, Price, ServerABConvert } from '@abconvert/headless';
import type { MiddlewarePlan, NextOptions } from '@abconvert/headless/next';

​Entry points

​createABConvert

​Options

​A client made with pageKey

​Methods

​getAssignment

​getAssignments

​getFeature

​getPriceByVariantId

​getPriceByProductId

​formatPrice

​getShippingRates

​getFreeShippingThreshold

​getOffers

​getVisitorId

​getCountry

​forceTestGroup

​clearForcedTestGroup

​getCartAttributes

​getCartLineAttributes

​getCheckoutUrl

​getPageKey

​getRedirectUrl

​getClientState

​getPageState

​isPageTested

​isTesting

​getSetCookieHeaders

​refreshTests

​track

​trackExposure

​setConsent

​Browser client

​hydrateABConvert

​React

​ABConvertProvider

​useABConvert

​Next.js

​abconvertMiddleware

​planMiddleware

​createABConvert on Next.js

​Hydrogen

​createABConvert on Hydrogen

​ABConvertProvider on Hydrogen

​keepPrivateWhenTested

​ABConvertCartAttributes

​useCartReadyForCheckout

​Objects

​Feature test fields

​CartAttribute

​CheckoutLine

​ClientState

​PageState

​TypeScript

Entry points

createABConvert

Options

A client made with pageKey

Methods

getAssignment

getAssignments

getFeature

getPriceByVariantId

getPriceByProductId

formatPrice

getShippingRates

getFreeShippingThreshold

getOffers

getVisitorId

getCountry

forceTestGroup

clearForcedTestGroup

getCartAttributes

getCartLineAttributes

getCheckoutUrl

getPageKey

getRedirectUrl

getClientState

getPageState

isPageTested

isTesting

getSetCookieHeaders

refreshTests

track

trackExposure

setConsent

Browser client

hydrateABConvert

React

ABConvertProvider

useABConvert

Next.js

abconvertMiddleware

planMiddleware

createABConvert on Next.js

Hydrogen

createABConvert on Hydrogen

ABConvertProvider on Hydrogen

keepPrivateWhenTested

ABConvertCartAttributes

useCartReadyForCheckout

Objects

Feature test fields

CartAttribute

CheckoutLine

ClientState

PageState

TypeScript