Browser SDK reference

The script exposes window.sideshift after loading. Calls made before consent do not queue events for later delivery. Connect consent using the installation guide.

Standard events

Call these methods after the script has loaded. Do not include customer names, addresses, email addresses, payment details, or other personal information in event properties.

Product view

window.sideshift.productViewed({
  productId: 'shirt-blue',
  productName: 'Blue shirt',
  price: 32.50,
  currency: 'USD'
});

A product view is sent once per product and page path for the current document.

Add to cart

Call this after your cart confirms that the item was added:

window.sideshift.addToCart({
  productId: 'shirt-blue',
  quantity: 2,
  price: 32.50,
  currency: 'USD'
});

Repeated events for the same product and quantity within two seconds are skipped.

Checkout started

window.sideshift.checkoutStarted({ value: 65, currency: 'USD' });

Checkout completed

Call this on your order confirmation page:

window.sideshift.checkout({
  orderId: 'order-1042',
  value: 65,
  currency: 'USD'
});

The pixel deduplicates each order ID within the browser session. Submit the order to the server API as well.

Custom event

window.sideshift.track('size_guide_opened', { productId: 'shirt-blue' });

Custom events appear in tracking diagnostics. They do not change commission amounts.

Visitor ID

const visitorId = window.sideshift.getVisitorId();

This returns null before consent. After consent, the ID is stored in the ss_vid_YOUR_STORE_ID cookie for up to 30 days. The attribution window is seven days; cookie lifetime does not extend it. Pass the ID to your server with the checkout request and store it with the order. If your server receives the store cookie, it can read that cookie directly. Do not replace a missing ID with a guessed or shared ID.

Event IDs and delivery

Methods that accept a data object accept an optional event_id string (1–200 characters). Use a stable ID when retrying the same action. Otherwise, the pixel generates one. Its bounded network retries reuse that ID. Custom event deduplication includes both event name and ID; use a new ID for a new action.

window.sideshift.track('lead', {
  event_id: 'lead-form-submission-1042',
  value: 0,
  currency: 'USD'
});

Custom names are trimmed to 250 characters. SideShift’s stored generic properties are limited to product name, event name, currency, price, value, and quantity, plus a sanitized page origin. Product and order IDs use the corresponding standard methods. Arbitrary custom properties are not stored. Prices and values here are major-unit display values, never authoritative purchase amounts. Do not use track('purchase') as an order integration. Browser purchase, checkout, subscription, and trial aliases do not create verified orders or advertising purchases. Use the Orders API.

Utility methods

Method	Result
`setConsent(boolean)`	Grants or withdraws the pixel’s consent state.
`getVisitorId()`	SideShift visitor ID, or `null` before consent.
`getAdvertisingContext()`	Currently available advertising context, or `null`.
`getAdvertisingContextAsync()`	Resolves after a bounded attempt to load the optional advertising destination; may return `null`.
`shopifyCartAttributes(existing)`	Preserves existing cart attributes and replaces `sideshift_visitor_id`; returns an empty visitor value without consent.

Advertising context is optional and is not a substitute for getVisitorId(). See advertising measurement.

Overview

Guides

SideShift Pixel

OAuth 2.1 & MCP

Legacy API (Deprecated)

Browser SDK reference

Standard events

Product view

Add to cart

Checkout started

Checkout completed

Custom event

Visitor ID

Event IDs and delivery

Utility methods

​Standard events

​Product view

​Add to cart

​Checkout started

​Checkout completed

​Custom event

​Visitor ID

​Event IDs and delivery

​Utility methods

Standard events

Product view

Add to cart

Checkout started

Checkout completed

Custom event

Visitor ID

Event IDs and delivery

Utility methods