Before you integrate

The Headless SDK lets custom Shopify storefronts sell Shipping Protection (SP) and Product Protection (PP). These storefronts are built without a Liquid theme, for example with Hydrogen, Next.js, or Nuxt. Reading this page takes about five minutes. You’ll learn how responsibilities split between the SDK and your storefront, what to prepare, which store settings to confirm with your account manager (AM), and which pages to read next.

What the SDK does and what you build

Area	The SDK	Your storefront
UI	Renders the SP panel, the PP panel, and their modals	Renders product pages, cart page, cart drawer, and checkout buttons
Pricing	Calculates SP quotes and PP plan prices	—
Cart writes	With the default adapter, writes fee lines and protection lines through the Storefront API. With an adapter, uses your endpoints. pp.addToCart drives the main product write, synchronization, and protection in one call	Adds main products from the pp.addToCart callback, updates quantities, removes lines, navigates to checkout
State sync	Calls your onCartChange callback after an SDK cart write or a confirmed syncCart. The callback reports confirmed facts only and does not signal business success	Calls syncCart(cart.id) after modifying the cart

The SDK renders panels and modals, including panel switches and modal buttons, without rewriting your existing buttons. Panels mount inside the configured containers. The SDK mounts modals separately. You render the checkout, add-to-cart, and cart add-protection buttons and call the corresponding SDK method from each click handler, as shown in each scenario guide.

Don’t write the same lines twice

The SDK writes fee lines and protection lines to the cart directly. Do not write those same lines through the Xcotton OpenAPI, or the same coverage will be added twice. Use the OpenAPI only for server-side capabilities outside the SDK’s scope.

Checklist

• The Xcotton Shopify plugin is installed on the store.
• You have the store’s Shopify Storefront API public access token (used by the default adapter to read and write the cart).
• The store is configured to run SDK v0.3 (version code 030). These docs and the type definitions apply to v0.3 only. If your store runs v0.2 (024), read Upgrade from v0.2 to v0.3 first.
• Your pages can supply three values to the SDK at startup: the active market’s country, currency, and language.

Country and currency must match Shopify Markets

The country passed to the SDK must match both the cart’s buyer country and the active Shopify Markets country, and currency must be the currency that market actually settles in. The cart’s own currency must match currency. The currency guard rejects a mismatch. A mismatched country is not rejected by the guard, but it can cause a mismatch between the panel price, fee line, and checkout total. language can change independently. It sets the panel copy and the language parameter for Storefront queries and quote requests. It never changes the checkout currency.

Settings your account manager (AM) configures

Your account manager (AM) configures the following behaviors in the back office. They cannot be overridden from frontend code. Because they determine which integration code you write, confirm each item before you start:

Setting	Values	Impact on your code
SP enabled	On / off	When off, window.xcotton.sp is undefined. Skip all SP guides
PP enabled	On / off	When off, window.xcotton.pp is undefined. Skip all PP guides
SP integration mode	cart, checkout, checkout+	Determines how you wire your checkout buttons. See Integration modes
SP panel style and copy	With switch (cart / checkout) / price only (checkout+)	Match the panel style to the integration mode: cart / checkout use a switch to express intent, while checkout+ uses two storefront checkout buttons
SP switch default state	On / off	Initial switch state the first time a visitor opens the cart
PP panel theme and copy	—	No code changes required
Open PP plan modal on add to cart	Yes / no	canBePopup() decides whether to open a modal when no plan is selected.pp.addToCart() reuses the same check
Show cart add-protection button	Yes / no	When off, getCartQuotes() returns { enabled: false, quotes: [] }

Glossary

Subsequent pages use these terms throughout:

Term	Meaning
Shipping Protection (SP)	Order-level shipping coverage priced for the entire cart. When added, the cart contains one fee line.
Product Protection (PP)	Item-level coverage priced per product. When added, a protection line is placed alongside the main product line.
fee line	The cart line written by SP for the Shipping Protection (SP) charge.
protection line	The cart line written by PP, linked to a specific main product line.
main product line	The Storefront API CartLine representing a regular product purchased by the customer.
integration mode	Controls when the SP fee line is written to the cart: cart, checkout, or checkout+.
panel	The SP or PP UI rendered by the SDK inside a container element you provide.
binding the cart	Calling syncCart(cartId) to tell the SDK which cart is active. The same method handles the first bind, cart switches, and same-cart refreshes.
adapter	Optional. Replaces the SDK’s default Storefront API client when cart operations go through your own API or BFF.

Reading path

1. Quick start (required): load the SDK and render the SP panel on the cart page.
2. Keep the cart in sync (required): understand how syncCart and onCartChange divide responsibilities. Most integration bugs come from mixing them up.
3. If SP is enabled: read Integration modes. For checkout or checkout+, continue to Checkout mode or Checkout+ mode.
4. If PP is enabled: read Add product protection, then Product protection modal and Cart add-protection button as needed.
5. Advanced and reference: if cart requests go through your own API or BFF, read Use your own cart API. For full method signatures, types, and error messages, see the SDK Reference.