JavaScript API Methods

Complete reference for all JavaScript methods available in the Campaign Cart SDK.

Getting Started

The SDK exposes methods through the window.next object after initialization.

Initialization Detection

// Check if SDK is ready
if (window.next) {
  // SDK is ready, use it directly
  next.addItem({ packageId: 1 });
} else {
  // Queue for later execution
  window.nextReady = window.nextReady || [];
  window.nextReady.push(function() {
    next.addItem({ packageId: 1 });
  });
}

// Or listen for initialization event
document.addEventListener('next:initialized', function(event) {
  // SDK is ready
  console.log('SDK initialized at', new Date(event.detail.timestamp));
  next.addItem({ packageId: 1 });
});

Cart Methods
Campaign & Package Methods
Coupon Methods
Shipping Methods
Tracking & Analytics Methods
Upsell Methods
Event Methods
Utility Methods
Debug API

Cart Methods

addItem

Adds an item to the cart. Note: This method requires an options object, not a direct package ID.

// ✅ CORRECT - Pass an object with packageId property
await next.addItem({ 
  packageId: 123, 
  quantity: 2 
});

// ✅ CORRECT - Quantity is optional (defaults to 1)
await next.addItem({ packageId: 123 });

// ❌ WRONG - Don't pass packageId directly
// next.addItem(123); // This won't work!

Parameters:

options (object): Required options object
- options.packageId (number): Package ID to add
- options.quantity (number, optional): Quantity to add (default: 1)

Returns: Promise<void>

removeItem

Removes an item from the cart. Requires an options object.

// ✅ CORRECT
await next.removeItem({ packageId: 123 });

// ❌ WRONG
// next.removeItem(123); // This won't work!

Parameters:

options (object): Required options object
- options.packageId (number): Package ID to remove

Returns: Promise<void>

updateQuantity

Updates the quantity of an item in the cart. Requires an options object.

// ✅ CORRECT
await next.updateQuantity({ 
  packageId: 123, 
  quantity: 5 
});

// ❌ WRONG
// next.updateQuantity(123, 5); // This won't work!

Parameters:

options (object): Required options object
- options.packageId (number): Package ID to update
- options.quantity (number): New quantity

Returns: Promise<void>

clearCart

Removes all items from the cart.

await next.clearCart();

Returns: Promise<void>

hasItemInCart

Checks if an item is in the cart. Requires an options object.

// ✅ CORRECT
const hasItem = next.hasItemInCart({ packageId: 123 });
console.log('Item in cart:', hasItem); // true or false

// ❌ WRONG
// next.hasItemInCart(123); // This won't work!

Parameters:

options (object): Required options object
- options.packageId (number): Package ID to check

Returns: boolean

getCartData

Returns comprehensive cart data including enriched items, totals, campaign data, and applied coupons.

const cartData = next.getCartData();
console.log(cartData);
// {
//   cartLines: [...],
//   cartTotals: { subtotal: {...}, total: {...}, ... },
//   campaignData: {...},
//   appliedCoupons: [...]
// }

Returns:

{
  cartLines: EnrichedCartLine[];
  cartTotals: CartTotals;
  campaignData: Campaign | null;
  appliedCoupons: AppliedCoupon[];
}

getCartTotals

Returns cart totals and pricing information.

const totals = next.getCartTotals();
console.log('Total:', totals.total.formatted); // "$99.99"
console.log('Subtotal:', totals.subtotal.formatted); // "$89.99"
console.log('Shipping:', totals.shipping.formatted); // "$10.00"

Returns: CartTotals object with subtotal, shipping, tax, discounts, and total

getCartCount

Returns the total number of items in the cart.

const count = next.getCartCount();
console.log('Items in cart:', count); // 3

Returns: number

Campaign & Package Methods

getCampaignData

Returns the loaded campaign data.

const campaign = next.getCampaignData();
if (campaign) {
  console.log('Campaign:', campaign.name);
  console.log('Currency:', campaign.currency);
  console.log('Packages:', campaign.packages);
}

Returns: Campaign | null

getPackage

Gets detailed information about a specific package.

const package = next.getPackage(123);
if (package) {
  console.log('Package name:', package.display_name);
  console.log('Price:', next.formatPrice(package.price));
}

Parameters:

id (number): Package ID

Returns: Package | null

Coupon Methods

applyCoupon

Applies a coupon code to the cart.

const result = await next.applyCoupon('SAVE20');
if (result.success) {
  console.log('Coupon applied:', result.message);
  console.log('Discount amount:', result.data.amount);
} else {
  console.error('Coupon error:', result.message);
}

Parameters:

code (string): Coupon code to apply

Returns:

Promise<{
  success: boolean;
  message: string;
  data?: { amount: number; formatted: string; }
}>

removeCoupon

Removes a coupon from the cart.

next.removeCoupon('SAVE20');

Parameters:

code (string): Coupon code to remove

Returns: void

getCoupons

Returns all applied coupons.

const coupons = next.getCoupons();
coupons.forEach(coupon => {
  console.log(`${coupon.code}: ${coupon.amount.formatted} off`);
});

Returns: AppliedCoupon[]

validateCoupon

Validates a coupon without applying it.

const validation = next.validateCoupon('TESTCODE');
if (validation.valid) {
  console.log('Coupon is valid');
} else {
  console.log('Invalid:', validation.message);
}

Parameters:

code (string): Coupon code to validate

Returns:

{
  valid: boolean;
  message?: string;
}

calculateDiscountAmount

Calculates the discount amount for a given coupon definition.

const amount = next.calculateDiscountAmount(couponDefinition);
console.log('Discount amount:', amount);

Parameters:

coupon (DiscountDefinition): Coupon definition object

Returns: number - Calculated discount amount

Shipping Methods

getShippingMethods

Returns all available shipping methods from the campaign.

const methods = next.getShippingMethods();
console.log(methods);
// [
//   {ref_id: 1, code: "standard", price: "0.00"},
//   {ref_id: 2, code: "express", price: "12.99"}
// ]

Returns: Array<{ref_id: number; code: string; price: string}>

getSelectedShippingMethod

Returns the currently selected shipping method.

const selected = next.getSelectedShippingMethod();
if (selected) {
  console.log('Shipping:', selected.name, selected.price);
}

Returns: {id: number; name: string; price: number; code: string} | null

setShippingMethod

Sets the shipping method by ID.

// Set standard shipping (ID 1)
await next.setShippingMethod(1);

// Set express shipping (ID 2)
await next.setShippingMethod(2);

Parameters:

methodId (number): The ref_id of the shipping method from campaign data

Returns: Promise<void>

Throws: Error if shipping method ID is not found in campaign data

Tracking & Analytics Methods

trackViewItemList

Tracks when users view a list of products.

// Basic tracking
await next.trackViewItemList(['1', '2', '3']);

// With list context
await next.trackViewItemList(
  ['1', '2', '3'], 
  'homepage', 
  'Featured Products'
);

Parameters:

packageIds (Array<string|number>): Array of package IDs
listId (string, optional): Unique list identifier
listName (string, optional): Human-readable list name

Returns: Promise<void>

trackViewItem

Tracks when a single item is viewed.

await next.trackViewItem('1');

Parameters:

packageId (string|number): Package ID viewed

Returns: Promise<void>

trackAddToCart

Tracks when an item is added to cart.

await next.trackAddToCart('1', 2);

Parameters:

packageId (string|number): Package ID added
quantity (number, optional): Quantity added (default: 1)

Returns: Promise<void>

trackRemoveFromCart

Tracks when an item is removed from cart.

await next.trackRemoveFromCart('1', 1);

Parameters:

packageId (string|number): Package ID removed
quantity (number, optional): Quantity removed (default: 1)

Returns: Promise<void>

trackBeginCheckout

Tracks when checkout process begins.

await next.trackBeginCheckout();

Returns: Promise<void>

trackPurchase

Tracks completed purchases.

// Track with order data
await next.trackPurchase(orderData);

Parameters:

orderData (any): Order data object

Returns: Promise<void>

trackCustomEvent

Tracks custom events with optional data.

// Simple custom event
await next.trackCustomEvent('video_played');

// Custom event with data
await next.trackCustomEvent('user_engagement', {
  section: 'hero',
  action: 'video_play',
  duration: 30
});

Parameters:

eventName (string): Custom event name
data (Record<string, any>, optional): Additional event data

Returns: Promise<void>

trackSignUp

Tracks user sign-up events.

await next.trackSignUp('[email protected]');

Parameters:

email (string): User's email address

Returns: Promise<void>

trackLogin

Tracks user login events.

await next.trackLogin('[email protected]');

Parameters:

email (string): User's email address

Returns: Promise<void>

setDebugMode (Analytics)

Enables or disables analytics debug mode.

await next.setDebugMode(true); // Enable debug logging

Parameters:

enabled (boolean): Enable or disable debug mode

Returns: Promise<void>

invalidateAnalyticsContext

Invalidates the analytics context, useful when switching between pages.

await next.invalidateAnalyticsContext();

Returns: Promise<void>

Upsell Methods

addUpsell

Adds upsell items to a completed order. Only available after order completion.

// Add single upsell
const result = await next.addUpsell({ 
  packageId: 123, 
  quantity: 1 
});

// Add multiple upsells at once
const result = await next.addUpsell({ 
  items: [
    { packageId: 123, quantity: 1 },
    { packageId: 456, quantity: 2 }
  ]
});

console.log('Upsells added:', result.addedLines);
console.log('Total upsell value:', result.totalValue);

Parameters:

options.packageId (number, optional): Single package ID to add
options.quantity (number, optional): Quantity for single item (default: 1)
options.items (Array, optional): Multiple items to add
- items[].packageId (number): Package ID
- items[].quantity (number, optional): Quantity (default: 1)

Returns:

Promise<{
  order: Order;
  addedLines: OrderLine[];
  totalValue: number;
}>

Throws: Error if no order exists or order doesn't support upsells

canAddUpsells

Checks if upsells can be added to the current order.

if (next.canAddUpsells()) {
  console.log('Order supports upsells');
}

Returns: boolean

getCompletedUpsells

Returns array of package IDs that have been added as upsells.

const completedUpsells = next.getCompletedUpsells();
console.log('Upsells added:', completedUpsells); // ['123', '456']

Returns: string[]

isUpsellAlreadyAdded

Checks if a specific package has already been added as an upsell.

if (next.isUpsellAlreadyAdded(123)) {
  console.log('This upsell was already added');
}

Parameters:

packageId (number): Package ID to check

Returns: boolean

Event Methods

on

Subscribe to internal SDK events.

// Listen for cart updates
next.on('cart:updated', (cartState) => {
  console.log('Cart updated:', cartState.items.length, 'items');
});

// Listen for item additions
next.on('cart:item-added', (data) => {
  console.log('Item added:', data.packageId);
});

Parameters:

event (string): Event name from EventMap
handler (function): Event handler function

Returns: void

Example:

// Subscribe to multiple events
next.on('cart:item-added', (data) => {
  showNotification(`${data.packageName} added to cart`);
});

next.on('order:completed', (order) => {
  trackConversion(order);
});

off

Unsubscribe from internal SDK events.

const handler = (data) => console.log(data);

// Add listener
next.on('cart:updated', handler);

// Later, remove listener
next.off('cart:updated', handler);

Parameters:

event (string): Event name
handler (function): Handler function to remove (must be the same function reference)

Returns: void

Example:

// Store handler reference for cleanup
const cartHandler = (data) => {
  updateCartUI(data);
};

// Subscribe
next.on('cart:updated', cartHandler);

// Later, when component unmounts
next.off('cart:updated', cartHandler);

For a complete list of all 34 available events, event data structures, initialization callbacks, and best practices, see the Events Reference.

Utility Methods

formatPrice

Formats a price value according to campaign currency.

const formatted = next.formatPrice(19.99); // "$19.99"
const euros = next.formatPrice(19.99, 'EUR'); // "€19.99"

Parameters:

amount (number): Price amount to format
currency (string, optional): Currency code (uses campaign currency if not provided)

Returns: string

validateCheckout

Validates if the cart is ready for checkout.

const validation = next.validateCheckout();
if (!validation.valid) {
  console.error('Cannot checkout:', validation.errors);
}

Returns:

{
  valid: boolean;
  errors?: string[];
}

Debug API

The debug API provides powerful utilities for development and troubleshooting. Available only when debug mode is enabled with ?debugger=true.

Accessing Debug Mode

// Check if debug mode is available
if (window.nextDebug) {
  console.log('Debug mode available');
}

Store Access

Direct access to all internal stores:

// Cart store
const cartState = nextDebug.stores.cart.getState();
console.log('Cart items:', cartState.items);

// Campaign store
const campaignState = nextDebug.stores.campaign.getState();
console.log('Campaign data:', campaignState.data);

// Config store
const configState = nextDebug.stores.config.getState();
console.log('API key:', configState.apiKey);

// Checkout store
const checkoutState = nextDebug.stores.checkout.getState();

// Order store
const orderState = nextDebug.stores.order.getState();

// Attribution store
const attributionState = nextDebug.stores.attribution.getState();

Cart Debug Methods

// Quick cart operations
nextDebug.addToCart(123);        // Add single item
nextDebug.addToCart(123, 3);     // Add with quantity
nextDebug.removeFromCart(123);   // Remove item
nextDebug.updateQuantity(123, 5); // Update quantity

// Add test items (packages 2, 7, 9)
nextDebug.addTestItems();

Campaign Debug Methods

// Reload campaign data
await nextDebug.loadCampaign();

// Clear campaign cache
nextDebug.clearCampaignCache();

// Get cache information
const cacheInfo = nextDebug.getCacheInfo();

// Inspect specific package
nextDebug.inspectPackage(123);

// Test shipping methods
await nextDebug.testShippingMethod(1);

Analytics Debug Methods

// Get analytics status
const status = await nextDebug.analytics.getStatus();

// Get loaded providers
const providers = await nextDebug.analytics.getProviders();

// Track test event
await nextDebug.analytics.track('test_event', { test: true });

// Enable analytics debug mode
await nextDebug.analytics.setDebugMode(true);

// Invalidate analytics context
await nextDebug.analytics.invalidateContext();

Attribution Debug Methods

// Debug attribution data
nextDebug.attribution.debug();

// Get attribution for API
const attribution = nextDebug.attribution.get();

// Set funnel name
nextDebug.attribution.setFunnel('debug-funnel');

// Set Everflow click ID
nextDebug.attribution.setEvclid('test-evclid-123');

// Get current funnel
const funnel = nextDebug.attribution.getFunnel();

// Clear persisted funnel
nextDebug.attribution.clearFunnel();

System Debug Methods

// Direct SDK access
nextDebug.sdk.addItem({ packageId: 123 });

// Get initialization stats
const stats = nextDebug.getStats();

// Reinitialize SDK
await nextDebug.reinitialize();

// Test mode manager
nextDebug.testMode.enable();
nextDebug.testMode.disable();
nextDebug.testMode.getConfig();

Debug Overlay Control

// Show/hide debug overlay
nextDebug.overlay.show();
nextDebug.overlay.hide();
nextDebug.overlay.toggle();

// Check visibility
const isVisible = nextDebug.overlay.isVisible();

Utilities - FOMO, exit intent, and debugging tools
Events - Complete event system documentation
Profiles API - Profile-based package mapping
Attribution API - Attribution tracking
URL Parameters API - URL parameter management
Data Attributes - HTML attribute reference

On this page