---
title: "Client-side cart sync"
description: "How the SDK keeps protection lines in step with the products they cover, how it works alongside cart apps and accelerated checkout, and what a theme must not do."
---

Once a shopper has a protection plan in the cart, the SureBright SDK keeps that line honest: the same quantity as the product it covers, one plan per product, and gone when the product is gone. It does this in the browser, on every page the SDK runs on, without any code from the theme. The server-side [Cart Validator](/shopify/enable-surebright-cart-validator) is the backstop at checkout; cart sync is what stops most problems reaching it.

## When sync runs

A sync cycle is scheduled on page load, whenever the cart changes (the SDK watches cart requests and cart DOM re-renders), after the SDK adds a plan, after a shopper add-to-cart, and, on platforms that expose it, when checkout starts. Cycles are debounced by 600 ms so a burst of cart writes produces one read.

Before reading the cart the SDK waits for any add-to-cart it has seen start to land, up to a cap. A read taken while a write is in flight is never trusted for a deletion. A circuit breaker stops sync after 5 cycles in 10 seconds so a theme that re-renders the cart on every write cannot put the SDK in a loop.

## How protection lines are recognised and matched

A cart line is a SureBright protection line when its title contains `Protection Powered by SureBright`, `Product Warranty Powered by SureBright` or `SureBright Protection Plan`, its handle matches `surebright-*` or `sb-protection-*`, or it carries the `_sbQuoteId` property. SureBright can add store-specific titles to this list.

A protection line is matched to the product it covers through its `_variantId` property, which holds the covered product's variant id. Lines that cover a cart line rather than a variant use `_lineItemKey`. Shipping-protection lines (`_sbQuotePlatform = PLATFORM_SHIPPING_INSURANCE`) and registration-page plans (`REGISTRATION_POST_PURCHASE`) are left out of sync entirely.

## What sync corrects

| Situation | What the SDK does |
| --- | --- |
| Product quantity changed | Raises or lowers the protection line so the covered units equal the product units, counted across every cart line of that variant. A store can cap units per product. |
| Two different plans for the same product | Keeps the most recently added (by `_sbAddedAt`) and removes the other. Two lines of the same plan are not treated as duplicates. |
| Protection with no `_variantId` or `_lineItemKey` | Removed. There is nothing to match it to. |
| Covered product removed from the cart | The protection line is removed. |
| More protection units than product units | Trimmed to the product quantity. |
| Bundle component plans | Kept at bundle quantity times component quantity, one line per component; see [Bundles](/shopify/bundles). |
| Post-purchase plan (`PLATFORM_POST_PURCHASE`) | Not matched to a cart product. Collapsed to one line per covered product and locked to `_sbPurchasedQuantity`. |

The orphan rules (no key, product gone) can be set per store to keep the line instead of removing it. In that case the SDK logs a warning and leaves the Cart Validator to block checkout.

## Removing orphans before checkout

On Shopify Online Store themes a cart read is reliable, so an orphaned plan is removed on the first sync pass. On Hydrogen and Shopyflow the cart can briefly under-report its lines mid-mutation, so any removal justified by a missing product has to appear in two consecutive reads, about 2.5 seconds apart, before it is executed. Duplicate removals are never deferred, because a transient read cannot invent a second line.

After writing, the SDK re-reads the cart 300 ms later and verifies each operation landed. Failed writes are retried up to 3 times with back-off. A write the store keeps refusing (for example an HTTP 422 because the cart caps units of a variant) is given up after 2 attempts, logged as `Coverage left mismatched`, and not re-issued until the target quantity changes. When at least one write succeeded the SDK refreshes the cart page or drawer so the shopper sees the result; on themes without section rendering this is a full reload, and the SDK waits for its own pending writes to finish before navigating.

## How add-to-cart is intercepted

Sync fixes the cart after the fact; interception is how the plan gets in at the moment of the add. Per store, SureBright configures an ordered pipeline of hooks, each with a trigger, an extractor for the variant and quantity, and a matcher:

| Hook | What it catches |
| --- | --- |
| `FORM_SUBMIT` | The product form posting to `/cart/add`. |
| `BUTTON_CLICK` | The add-to-cart button itself, used when a store owns `window.fetch` (Shopyflow) so the SDK writes the plan after the native add instead of rewriting the request. |
| `FETCH`, `XHR` | AJAX adds to `/cart/add.js`, JSON, form-encoded or `FormData`. A request carrying several items (an add-on app bundling extras with the product) counts as the product's add when one item is the product on offer. |
| `GRAPHQL` | Storefront API `cartCreate` and `cartLinesAdd` mutations, used by accelerated checkout and headless carts. |

The SDK's own cart requests carry an `X-SB-Internal: 1` header so they are never re-intercepted. In the quick-view surface every hook is forced to act before the base add completes, because themes often navigate right after it.

## Third-party cart apps

If an app renders your cart instead of the theme, the SDK has to ask that app to repaint after it writes, and it has to recognise the app's rows. Two apps are supported today:

| App | How the SDK works with it |
| --- | --- |
| Rebuy Smart Cart | Rows are found by `.rebuy-cart__flyout-item` (or the drawer line selector configured for your store). After a write the SDK waits for `window.Rebuy.Cart` (the `rebuy:cart.ready` event, up to 8 s) and calls `fetchShopifyCart` so the flyout re-reads the cart. |
| UpCart | Rows are `.upcart-product-item`. The SDK waits for UpCart's React app to mount (up to 3 s) and calls `upcartRefreshCart()`. Its own `/cart/add` requests carry `upcart=1&opens_cart=never` so the drawer re-reads without popping open. |

SureBright declares the cart app for your store; the presence of the app's script is not enough, since many stores install Rebuy for upsells while the theme cart stays in charge. If you switch cart apps, tell SureBright.

## Accelerated checkout (Shop Pay, Buy with Shop)

Dynamic checkout buttons create the cart with a `cartCreate` mutation and leave for checkout in the same instant, so there is no cart page for sync to fix. When Shop Pay support is enabled for your store, the SDK adds a `GRAPHQL` step that holds that mutation, adds the selected plan as a line with the usual properties, and lets it go. If no plan is selected and the store nudges, the offer pop-up opens and the request waits for the shopper's answer. The quick-view surface gets the same step. Without this flag, a "Buy with Shop" purchase carries no plan.

## What a theme developer must not do

- Do not rename, strip or re-key `_sb*`, `_variantId`, `_lineItemKey` or `_bundle*` line properties anywhere between the cart and the order. They are how the order is matched to the quote; see [Cart line-item properties](/frontend-widget-integration/frontend-widget-kit/javascript-injection#cart-line-item-properties).
- Do not replace `window.fetch` or `XMLHttpRequest` after the SDK has loaded without calling through to the original. The SDK observes cart responses to know when to sync; a wrapper that swallows them blinds it. If you must wrap, load your wrapper first.
- Do not change the quantity of a SureBright line yourself. Protection quantity follows the product it covers, and the next cycle puts it back. On shipping-protection and post-purchase rows the SDK disables the theme's quantity stepper outright and keeps only the remove control.
- Do not merge cart lines client-side. Each add carries a distinct `_sbAddedAt` so plans stay separate; merging hides changes.
- Do not block or rewrite `/cart/change.js` and `/cart/update.js`. Sync writes through them.
- Do not load the SDK twice. The second load is ignored, but a theme and an app embed both loading different builds is a common source of confusion.
- Cart re-renders need no signal from you; the SDK observes them. If your theme re-renders collection grids client-side, dispatch `document.dispatchEvent(new CustomEvent("sb:cart-sections-refreshed"))` afterwards so the SDK re-hides SureBright's protection products in the new markup.

## Debugging

Add `?sb_debug` to the cart URL. Sync logs under `[SB] [SYNC]`: `Cart read` with the item count, `SyncResolver: plan assembled` with the operation count, `Deferred warranty removal pending second-read confirmation` when a removal is waiting, and `Executing sync plan` when writes go out. `[SB] [INTERCEPTOR]` lines show which hooks were installed and whether a request matched. `window.__SUREBRIGHT_DESTROY__()` removes the interceptors and observers if you need to compare against the theme alone.
